1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/manager/ssl/public/nsIX509CertDB.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,364 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIArray;
1.13 +interface nsIX509Cert;
1.14 +interface nsIX509Cert3;
1.15 +interface nsIFile;
1.16 +interface nsIInterfaceRequestor;
1.17 +interface nsIZipReader;
1.18 +interface nsIRecentBadCerts;
1.19 +interface nsIX509CertList;
1.20 +
1.21 +%{C++
1.22 +#define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1"
1.23 +%}
1.24 +
1.25 +typedef uint32_t AppTrustedRoot;
1.26 +
1.27 +[scriptable, function, uuid(0927baea-622d-4e41-a76d-255af426e7fb)]
1.28 +interface nsIOpenSignedAppFileCallback : nsISupports
1.29 +{
1.30 + void openSignedAppFileFinished(in nsresult rv,
1.31 + in nsIZipReader aZipReader,
1.32 + in nsIX509Cert3 aSignerCert);
1.33 +};
1.34 +
1.35 +/**
1.36 + * This represents a service to access and manipulate
1.37 + * X.509 certificates stored in a database.
1.38 + */
1.39 +[scriptable, uuid(7446a5b1-84ca-491f-a2fe-0bc60a71ffa5)]
1.40 +interface nsIX509CertDB : nsISupports {
1.41 +
1.42 + /**
1.43 + * Constants that define which usages a certificate
1.44 + * is trusted for.
1.45 + */
1.46 + const unsigned long UNTRUSTED = 0;
1.47 + const unsigned long TRUSTED_SSL = 1 << 0;
1.48 + const unsigned long TRUSTED_EMAIL = 1 << 1;
1.49 + const unsigned long TRUSTED_OBJSIGN = 1 << 2;
1.50 +
1.51 + /**
1.52 + * Given a nickname and optionally a token,
1.53 + * locate the matching certificate.
1.54 + *
1.55 + * @param aToken Optionally limits the scope of
1.56 + * this function to a token device.
1.57 + * Can be null to mean any token.
1.58 + * @param aNickname The nickname to be used as the key
1.59 + * to find a certificate.
1.60 + *
1.61 + * @return The matching certificate if found.
1.62 + */
1.63 + nsIX509Cert findCertByNickname(in nsISupports aToken,
1.64 + in AString aNickname);
1.65 +
1.66 + /**
1.67 + * Will find a certificate based on its dbkey
1.68 + * retrieved by getting the dbKey attribute of
1.69 + * the certificate.
1.70 + *
1.71 + * @param aDBkey Database internal key, as obtained using
1.72 + * attribute dbkey in nsIX509Cert.
1.73 + * @param aToken Optionally limits the scope of
1.74 + * this function to a token device.
1.75 + * Can be null to mean any token.
1.76 + */
1.77 + nsIX509Cert findCertByDBKey(in string aDBkey, in nsISupports aToken);
1.78 +
1.79 + /**
1.80 + * Obtain a list of certificate nicknames from the database.
1.81 + * What the name is depends on type:
1.82 + * user, ca, or server cert - the nickname
1.83 + * email cert - the email address
1.84 + *
1.85 + * @param aToken Optionally limits the scope of
1.86 + * this function to a token device.
1.87 + * Can be null to mean any token.
1.88 + * @param aType Type of certificate to obtain
1.89 + * See certificate type constants in nsIX509Cert.
1.90 + * @param count The number of nicknames in the returned array
1.91 + * @param certNameList The returned array of certificate nicknames.
1.92 + */
1.93 + void findCertNicknames(in nsISupports aToken,
1.94 + in unsigned long aType,
1.95 + out unsigned long count,
1.96 + [array, size_is(count)] out wstring certNameList);
1.97 +
1.98 + /**
1.99 + * Find user's own email encryption certificate by nickname.
1.100 + *
1.101 + * @param aNickname The nickname to be used as the key
1.102 + * to find the certificate.
1.103 + *
1.104 + * @return The matching certificate if found.
1.105 + */
1.106 + nsIX509Cert findEmailEncryptionCert(in AString aNickname);
1.107 +
1.108 + /**
1.109 + * Find user's own email signing certificate by nickname.
1.110 + *
1.111 + * @param aNickname The nickname to be used as the key
1.112 + * to find the certificate.
1.113 + *
1.114 + * @return The matching certificate if found.
1.115 + */
1.116 + nsIX509Cert findEmailSigningCert(in AString aNickname);
1.117 +
1.118 + /**
1.119 + * Find a certificate by email address.
1.120 + *
1.121 + * @param aToken Optionally limits the scope of
1.122 + * this function to a token device.
1.123 + * Can be null to mean any token.
1.124 + * @param aEmailAddress The email address to be used as the key
1.125 + * to find the certificate.
1.126 + *
1.127 + * @return The matching certificate if found.
1.128 + */
1.129 + nsIX509Cert findCertByEmailAddress(in nsISupports aToken,
1.130 + in string aEmailAddress);
1.131 +
1.132 + /**
1.133 + * Use this to import a stream sent down as a mime type into
1.134 + * the certificate database on the default token.
1.135 + * The stream may consist of one or more certificates.
1.136 + *
1.137 + * @param data The raw data to be imported
1.138 + * @param length The length of the data to be imported
1.139 + * @param type The type of the certificate, see constants in nsIX509Cert
1.140 + * @param ctx A UI context.
1.141 + */
1.142 + void importCertificates([array, size_is(length)] in octet data,
1.143 + in unsigned long length,
1.144 + in unsigned long type,
1.145 + in nsIInterfaceRequestor ctx);
1.146 +
1.147 + /**
1.148 + * Import another person's email certificate into the database.
1.149 + *
1.150 + * @param data The raw data to be imported
1.151 + * @param length The length of the data to be imported
1.152 + * @param ctx A UI context.
1.153 + */
1.154 + void importEmailCertificate([array, size_is(length)] in octet data,
1.155 + in unsigned long length,
1.156 + in nsIInterfaceRequestor ctx);
1.157 +
1.158 + /**
1.159 + * Import a server machine's certificate into the database.
1.160 + *
1.161 + * @param data The raw data to be imported
1.162 + * @param length The length of the data to be imported
1.163 + * @param ctx A UI context.
1.164 + */
1.165 + void importServerCertificate([array, size_is(length)] in octet data,
1.166 + in unsigned long length,
1.167 + in nsIInterfaceRequestor ctx);
1.168 +
1.169 + /**
1.170 + * Import a personal certificate into the database, assuming
1.171 + * the database already contains the private key for this certificate.
1.172 + *
1.173 + * @param data The raw data to be imported
1.174 + * @param length The length of the data to be imported
1.175 + * @param ctx A UI context.
1.176 + */
1.177 + void importUserCertificate([array, size_is(length)] in octet data,
1.178 + in unsigned long length,
1.179 + in nsIInterfaceRequestor ctx);
1.180 +
1.181 + /**
1.182 + * Delete a certificate stored in the database.
1.183 + *
1.184 + * @param aCert Delete this certificate.
1.185 + */
1.186 + void deleteCertificate(in nsIX509Cert aCert);
1.187 +
1.188 + /**
1.189 + * Modify the trust that is stored and associated to a certificate within
1.190 + * a database. Separate trust is stored for
1.191 + * One call manipulates the trust for one trust type only.
1.192 + * See the trust type constants defined within this interface.
1.193 + *
1.194 + * @param cert Change the stored trust of this certificate.
1.195 + * @param type The type of the certificate. See nsIX509Cert.
1.196 + * @param trust A bitmask. The new trust for the possible usages.
1.197 + * See the trust constants defined within this interface.
1.198 + */
1.199 + void setCertTrust(in nsIX509Cert cert,
1.200 + in unsigned long type,
1.201 + in unsigned long trust);
1.202 +
1.203 + /**
1.204 + * @param cert The certificate for which to modify trust.
1.205 + * @param trustString decoded by CERT_DecodeTrustString. 3 comma separated
1.206 + * characters, indicating SSL, Email, and Obj signing
1.207 + * trust.
1.208 + */
1.209 + void setCertTrustFromString(in nsIX509Cert3 cert, in string trustString);
1.210 +
1.211 + /**
1.212 + * Query whether a certificate is trusted for a particular use.
1.213 + *
1.214 + * @param cert Obtain the stored trust of this certificate.
1.215 + * @param certType The type of the certificate. See nsIX509Cert.
1.216 + * @param trustType A single bit from the usages constants defined
1.217 + * within this interface.
1.218 + *
1.219 + * @return Returns true if the certificate is trusted for the given use.
1.220 + */
1.221 + boolean isCertTrusted(in nsIX509Cert cert,
1.222 + in unsigned long certType,
1.223 + in unsigned long trustType);
1.224 +
1.225 + /**
1.226 + * Import certificate(s) from file
1.227 + *
1.228 + * @param aToken Optionally limits the scope of
1.229 + * this function to a token device.
1.230 + * Can be null to mean any token.
1.231 + * @param aFile Identifies a file that contains the certificate
1.232 + * to be imported.
1.233 + * @param aType Describes the type of certificate that is going to
1.234 + * be imported. See type constants in nsIX509Cert.
1.235 + */
1.236 + void importCertsFromFile(in nsISupports aToken,
1.237 + in nsIFile aFile,
1.238 + in unsigned long aType);
1.239 +
1.240 + /**
1.241 + * Import a PKCS#12 file containing cert(s) and key(s) into the database.
1.242 + *
1.243 + * @param aToken Optionally limits the scope of
1.244 + * this function to a token device.
1.245 + * Can be null to mean any token.
1.246 + * @param aFile Identifies a file that contains the data
1.247 + * to be imported.
1.248 + */
1.249 + void importPKCS12File(in nsISupports aToken,
1.250 + in nsIFile aFile);
1.251 +
1.252 + /**
1.253 + * Export a set of certs and keys from the database to a PKCS#12 file.
1.254 + *
1.255 + * @param aToken Optionally limits the scope of
1.256 + * this function to a token device.
1.257 + * Can be null to mean any token.
1.258 + * @param aFile Identifies a file that will be filled with the data
1.259 + * to be exported.
1.260 + * @param count The number of certificates to be exported.
1.261 + * @param aCerts The array of all certificates to be exported.
1.262 + */
1.263 + void exportPKCS12File(in nsISupports aToken,
1.264 + in nsIFile aFile,
1.265 + in unsigned long count,
1.266 + [array, size_is(count)] in nsIX509Cert aCerts);
1.267 +
1.268 + /*
1.269 + * Decode a raw data presentation and instantiate an object in memory.
1.270 + *
1.271 + * @param base64 The raw representation of a certificate,
1.272 + * encoded as Base 64.
1.273 + * @return The new certificate object.
1.274 + */
1.275 + nsIX509Cert constructX509FromBase64(in string base64);
1.276 +
1.277 + /*
1.278 + * Decode a raw data presentation and instantiate an object in memory.
1.279 + *
1.280 + * @param certDER The raw representation of a certificate,
1.281 + * encoded as raw DER.
1.282 + * @param length The length of the DER string.
1.283 + * @return The new certificate object.
1.284 + */
1.285 + nsIX509Cert constructX509(in string certDER, in unsigned long length);
1.286 +
1.287 + /*
1.288 + * Obtain a reference to the appropriate service for recent
1.289 + * bad certificates. May only be called on the main thread.
1.290 + *
1.291 + * @param isPrivate True if the service for certs for private connections
1.292 + * is desired, false otherwise.
1.293 + * @return The requested service.
1.294 + */
1.295 + nsIRecentBadCerts getRecentBadCerts(in boolean isPrivate);
1.296 +
1.297 + /**
1.298 + * Verifies the signature on the given JAR file to verify that it has a
1.299 + * valid signature. To be considered valid, there must be exactly one
1.300 + * signature on the JAR file and that signature must have signed every
1.301 + * entry. Further, the signature must come from a certificate that
1.302 + * is trusted for code signing.
1.303 + *
1.304 + * On success, NS_OK, a nsIZipReader, and the trusted certificate that
1.305 + * signed the JAR are returned.
1.306 + *
1.307 + * On failure, an error code is returned.
1.308 + *
1.309 + * This method returns a nsIZipReader, instead of taking an nsIZipReader
1.310 + * as input, to encourage users of the API to verify the signature as the
1.311 + * first step in opening the JAR.
1.312 + */
1.313 + const AppTrustedRoot AppMarketplaceProdPublicRoot = 1;
1.314 + const AppTrustedRoot AppMarketplaceProdReviewersRoot = 2;
1.315 + const AppTrustedRoot AppMarketplaceDevPublicRoot = 3;
1.316 + const AppTrustedRoot AppMarketplaceDevReviewersRoot = 4;
1.317 + const AppTrustedRoot AppXPCShellRoot = 5;
1.318 + void openSignedAppFileAsync(in AppTrustedRoot trustedRoot,
1.319 + in nsIFile aJarFile,
1.320 + in nsIOpenSignedAppFileCallback callback);
1.321 +
1.322 + /*
1.323 + * Add a cert to a cert DB from a binary string.
1.324 + *
1.325 + * @param certDER The raw DER encoding of a certificate.
1.326 + * @param aTrust decoded by CERT_DecodeTrustString. 3 comma separated characters,
1.327 + * indicating SSL, Email, and Obj signing trust
1.328 + * @param aName name of the cert for display purposes.
1.329 + */
1.330 + void addCert(in ACString certDER, in string aTrust, in string aName);
1.331 +
1.332 + // Flags for verifyCertNow (these must match the values in CertVerifier.cpp):
1.333 + // Prevent network traffic. Doesn't work with classic verification.
1.334 + const uint32_t FLAG_LOCAL_ONLY = 1 << 0;
1.335 + // Do not fall back to DV verification after attempting EV validation.
1.336 + // Actually does prevent network traffic, but can cause a valid EV
1.337 + // certificate to not be considered valid.
1.338 + const uint32_t FLAG_MUST_BE_EV = 1 << 1;
1.339 +
1.340 + /** Warning: This interface is inteded to use only for testing only as:
1.341 + * 1. It can create IO on the main thread.
1.342 + * 2. It is in constant change, so in/out can change at any release.
1.343 + *
1.344 + * Obtain the verification result for a cert given a particular usage.
1.345 + * On success, the call returns 0, the chain built during verification,
1.346 + * and whether the cert is good for EV usage.
1.347 + * On failure, the call returns the PRErrorCode for the verification failure
1.348 + *
1.349 + * @param aCert Obtain the stored trust of this certificate
1.350 + * @param aUsage a integer representing the usage from NSS
1.351 + * @param aFlags flags as described above
1.352 + * @param verifedChain chain of verification up to the root if success
1.353 + * @param aHasEVPolicy bool that signified that the cert was an EV cert
1.354 + * @return 0 if success or the value or the error code for the verification
1.355 + * failure
1.356 + */
1.357 + int32_t /*PRErrorCode*/
1.358 + verifyCertNow(in nsIX509Cert aCert,
1.359 + in int64_t /*SECCertificateUsage*/ aUsage,
1.360 + in uint32_t aFlags,
1.361 + out nsIX509CertList verifiedChain,
1.362 + out bool aHasEVPolicy);
1.363 +
1.364 + // Clears the OCSP cache for the current certificate verification
1.365 + // implementation.
1.366 + void clearOCSPCache();
1.367 +};
