The Tor Browser: security/manager/ssl/public/nsIX509CertDB.idl@b8a032363ba2 (annotated)

security/manager/ssl/public/nsIX509CertDB.idl@b8a032363ba2 (annotated)

security/manager/ssl/public/nsIX509CertDB.idl

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* -*- 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();
 };

The Tor Browser / annotate

security/manager/ssl/public/nsIX509CertDB.idl@b8a032363ba2 (annotated)

security/manager/ssl/public/nsIX509CertDB.idl