diff -r 000000000000 -r 6474c204b198 security/manager/ssl/public/nsIX509CertDB.idl --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/security/manager/ssl/public/nsIX509CertDB.idl Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,364 @@ +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +interface nsIArray; +interface nsIX509Cert; +interface nsIX509Cert3; +interface nsIFile; +interface nsIInterfaceRequestor; +interface nsIZipReader; +interface nsIRecentBadCerts; +interface nsIX509CertList; + +%{C++ +#define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1" +%} + +typedef uint32_t AppTrustedRoot; + +[scriptable, function, uuid(0927baea-622d-4e41-a76d-255af426e7fb)] +interface nsIOpenSignedAppFileCallback : nsISupports +{ + void openSignedAppFileFinished(in nsresult rv, + in nsIZipReader aZipReader, + in nsIX509Cert3 aSignerCert); +}; + +/** + * This represents a service to access and manipulate + * X.509 certificates stored in a database. + */ +[scriptable, uuid(7446a5b1-84ca-491f-a2fe-0bc60a71ffa5)] +interface nsIX509CertDB : nsISupports { + + /** + * Constants that define which usages a certificate + * is trusted for. + */ + const unsigned long UNTRUSTED = 0; + const unsigned long TRUSTED_SSL = 1 << 0; + const unsigned long TRUSTED_EMAIL = 1 << 1; + const unsigned long TRUSTED_OBJSIGN = 1 << 2; + + /** + * Given a nickname and optionally a token, + * locate the matching certificate. + * + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + * @param aNickname The nickname to be used as the key + * to find a certificate. + * + * @return The matching certificate if found. + */ + nsIX509Cert findCertByNickname(in nsISupports aToken, + in AString aNickname); + + /** + * Will find a certificate based on its dbkey + * retrieved by getting the dbKey attribute of + * the certificate. + * + * @param aDBkey Database internal key, as obtained using + * attribute dbkey in nsIX509Cert. + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + */ + nsIX509Cert findCertByDBKey(in string aDBkey, in nsISupports aToken); + + /** + * Obtain a list of certificate nicknames from the database. + * What the name is depends on type: + * user, ca, or server cert - the nickname + * email cert - the email address + * + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + * @param aType Type of certificate to obtain + * See certificate type constants in nsIX509Cert. + * @param count The number of nicknames in the returned array + * @param certNameList The returned array of certificate nicknames. + */ + void findCertNicknames(in nsISupports aToken, + in unsigned long aType, + out unsigned long count, + [array, size_is(count)] out wstring certNameList); + + /** + * Find user's own email encryption certificate by nickname. + * + * @param aNickname The nickname to be used as the key + * to find the certificate. + * + * @return The matching certificate if found. + */ + nsIX509Cert findEmailEncryptionCert(in AString aNickname); + + /** + * Find user's own email signing certificate by nickname. + * + * @param aNickname The nickname to be used as the key + * to find the certificate. + * + * @return The matching certificate if found. + */ + nsIX509Cert findEmailSigningCert(in AString aNickname); + + /** + * Find a certificate by email address. + * + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + * @param aEmailAddress The email address to be used as the key + * to find the certificate. + * + * @return The matching certificate if found. + */ + nsIX509Cert findCertByEmailAddress(in nsISupports aToken, + in string aEmailAddress); + + /** + * Use this to import a stream sent down as a mime type into + * the certificate database on the default token. + * The stream may consist of one or more certificates. + * + * @param data The raw data to be imported + * @param length The length of the data to be imported + * @param type The type of the certificate, see constants in nsIX509Cert + * @param ctx A UI context. + */ + void importCertificates([array, size_is(length)] in octet data, + in unsigned long length, + in unsigned long type, + in nsIInterfaceRequestor ctx); + + /** + * Import another person's email certificate into the database. + * + * @param data The raw data to be imported + * @param length The length of the data to be imported + * @param ctx A UI context. + */ + void importEmailCertificate([array, size_is(length)] in octet data, + in unsigned long length, + in nsIInterfaceRequestor ctx); + + /** + * Import a server machine's certificate into the database. + * + * @param data The raw data to be imported + * @param length The length of the data to be imported + * @param ctx A UI context. + */ + void importServerCertificate([array, size_is(length)] in octet data, + in unsigned long length, + in nsIInterfaceRequestor ctx); + + /** + * Import a personal certificate into the database, assuming + * the database already contains the private key for this certificate. + * + * @param data The raw data to be imported + * @param length The length of the data to be imported + * @param ctx A UI context. + */ + void importUserCertificate([array, size_is(length)] in octet data, + in unsigned long length, + in nsIInterfaceRequestor ctx); + + /** + * Delete a certificate stored in the database. + * + * @param aCert Delete this certificate. + */ + void deleteCertificate(in nsIX509Cert aCert); + + /** + * Modify the trust that is stored and associated to a certificate within + * a database. Separate trust is stored for + * One call manipulates the trust for one trust type only. + * See the trust type constants defined within this interface. + * + * @param cert Change the stored trust of this certificate. + * @param type The type of the certificate. See nsIX509Cert. + * @param trust A bitmask. The new trust for the possible usages. + * See the trust constants defined within this interface. + */ + void setCertTrust(in nsIX509Cert cert, + in unsigned long type, + in unsigned long trust); + + /** + * @param cert The certificate for which to modify trust. + * @param trustString decoded by CERT_DecodeTrustString. 3 comma separated + * characters, indicating SSL, Email, and Obj signing + * trust. + */ + void setCertTrustFromString(in nsIX509Cert3 cert, in string trustString); + + /** + * Query whether a certificate is trusted for a particular use. + * + * @param cert Obtain the stored trust of this certificate. + * @param certType The type of the certificate. See nsIX509Cert. + * @param trustType A single bit from the usages constants defined + * within this interface. + * + * @return Returns true if the certificate is trusted for the given use. + */ + boolean isCertTrusted(in nsIX509Cert cert, + in unsigned long certType, + in unsigned long trustType); + + /** + * Import certificate(s) from file + * + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + * @param aFile Identifies a file that contains the certificate + * to be imported. + * @param aType Describes the type of certificate that is going to + * be imported. See type constants in nsIX509Cert. + */ + void importCertsFromFile(in nsISupports aToken, + in nsIFile aFile, + in unsigned long aType); + + /** + * Import a PKCS#12 file containing cert(s) and key(s) into the database. + * + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + * @param aFile Identifies a file that contains the data + * to be imported. + */ + void importPKCS12File(in nsISupports aToken, + in nsIFile aFile); + + /** + * Export a set of certs and keys from the database to a PKCS#12 file. + * + * @param aToken Optionally limits the scope of + * this function to a token device. + * Can be null to mean any token. + * @param aFile Identifies a file that will be filled with the data + * to be exported. + * @param count The number of certificates to be exported. + * @param aCerts The array of all certificates to be exported. + */ + void exportPKCS12File(in nsISupports aToken, + in nsIFile aFile, + in unsigned long count, + [array, size_is(count)] in nsIX509Cert aCerts); + + /* + * Decode a raw data presentation and instantiate an object in memory. + * + * @param base64 The raw representation of a certificate, + * encoded as Base 64. + * @return The new certificate object. + */ + nsIX509Cert constructX509FromBase64(in string base64); + + /* + * Decode a raw data presentation and instantiate an object in memory. + * + * @param certDER The raw representation of a certificate, + * encoded as raw DER. + * @param length The length of the DER string. + * @return The new certificate object. + */ + nsIX509Cert constructX509(in string certDER, in unsigned long length); + + /* + * Obtain a reference to the appropriate service for recent + * bad certificates. May only be called on the main thread. + * + * @param isPrivate True if the service for certs for private connections + * is desired, false otherwise. + * @return The requested service. + */ + nsIRecentBadCerts getRecentBadCerts(in boolean isPrivate); + + /** + * Verifies the signature on the given JAR file to verify that it has a + * valid signature. To be considered valid, there must be exactly one + * signature on the JAR file and that signature must have signed every + * entry. Further, the signature must come from a certificate that + * is trusted for code signing. + * + * On success, NS_OK, a nsIZipReader, and the trusted certificate that + * signed the JAR are returned. + * + * On failure, an error code is returned. + * + * This method returns a nsIZipReader, instead of taking an nsIZipReader + * as input, to encourage users of the API to verify the signature as the + * first step in opening the JAR. + */ + const AppTrustedRoot AppMarketplaceProdPublicRoot = 1; + const AppTrustedRoot AppMarketplaceProdReviewersRoot = 2; + const AppTrustedRoot AppMarketplaceDevPublicRoot = 3; + const AppTrustedRoot AppMarketplaceDevReviewersRoot = 4; + const AppTrustedRoot AppXPCShellRoot = 5; + void openSignedAppFileAsync(in AppTrustedRoot trustedRoot, + in nsIFile aJarFile, + in nsIOpenSignedAppFileCallback callback); + + /* + * Add a cert to a cert DB from a binary string. + * + * @param certDER The raw DER encoding of a certificate. + * @param aTrust decoded by CERT_DecodeTrustString. 3 comma separated characters, + * indicating SSL, Email, and Obj signing trust + * @param aName name of the cert for display purposes. + */ + void addCert(in ACString certDER, in string aTrust, in string aName); + + // Flags for verifyCertNow (these must match the values in CertVerifier.cpp): + // Prevent network traffic. Doesn't work with classic verification. + const uint32_t FLAG_LOCAL_ONLY = 1 << 0; + // Do not fall back to DV verification after attempting EV validation. + // Actually does prevent network traffic, but can cause a valid EV + // certificate to not be considered valid. + const uint32_t FLAG_MUST_BE_EV = 1 << 1; + + /** Warning: This interface is inteded to use only for testing only as: + * 1. It can create IO on the main thread. + * 2. It is in constant change, so in/out can change at any release. + * + * Obtain the verification result for a cert given a particular usage. + * On success, the call returns 0, the chain built during verification, + * and whether the cert is good for EV usage. + * On failure, the call returns the PRErrorCode for the verification failure + * + * @param aCert Obtain the stored trust of this certificate + * @param aUsage a integer representing the usage from NSS + * @param aFlags flags as described above + * @param verifedChain chain of verification up to the root if success + * @param aHasEVPolicy bool that signified that the cert was an EV cert + * @return 0 if success or the value or the error code for the verification + * failure + */ + int32_t /*PRErrorCode*/ + verifyCertNow(in nsIX509Cert aCert, + in int64_t /*SECCertificateUsage*/ aUsage, + in uint32_t aFlags, + out nsIX509CertList verifiedChain, + out bool aHasEVPolicy); + + // Clears the OCSP cache for the current certificate verification + // implementation. + void clearOCSPCache(); +};