gecko-dev/security/manager/ssl/nsIX509CertDB.idl

/* -*- 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 nsIFile;
interface nsIInterfaceRequestor;
interface nsIZipReader;
interface nsIX509CertList;
interface nsIInputStream;

%{C++
#define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1"
%}

typedef uint32_t AppTrustedRoot;

[scriptable, function, uuid(fc2b60e5-9a07-47c2-a2cd-b83b68a660ac)]
interface nsIOpenSignedAppFileCallback : nsISupports
{
  void openSignedAppFileFinished(in nsresult rv,
                                 in nsIZipReader aZipReader,
                                 in nsIX509Cert aSignerCert);
};

[scriptable, function, uuid(d5f97827-622a-488f-be08-d850432ac8ec)]
interface nsIVerifySignedDirectoryCallback : nsISupports
{
  void verifySignedDirectoryFinished(in nsresult rv,
                                     in nsIX509Cert aSignerCert);
};

/**
 * Callback type for use with asyncVerifyCertAtTime.
 * If aPRErrorCode is PRErrorCodeSuccess (i.e. 0), aVerifiedChain represents the
 * verified certificate chain determined by asyncVerifyCertAtTime. aHasEVPolicy
 * represents whether or not the end-entity certificate verified as EV.
 * If aPRErrorCode is non-zero, it represents the error encountered during
 * verification. aVerifiedChain is null in that case and aHasEVPolicy has no
 * meaning.
 */
[scriptable, function, uuid(49e16fc8-efac-4f57-8361-956ef6b960a4)]
interface nsICertVerificationCallback : nsISupports {
  void verifyCertFinished(in int32_t aPRErrorCode,
                          in nsIX509CertList aVerifiedChain,
                          in bool aHasEVPolicy);
};

/**
 * This represents a service to access and manipulate
 * X.509 certificates stored in a database.
 */
[scriptable, uuid(5c16cd9b-5a73-47f1-ab0f-11ede7495cce)]
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;

  /**
   *  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.
   */
  [must_use]
  nsIX509Cert findCertByDBKey(in ACString aDBkey);

  /**
   *  Find a certificate by email address.
   *
   *  @param aEmailAddress The email address to be used as the key
   *                       to find the certificate.
   *
   *  @return The matching certificate if found.
   */
  [must_use]
  nsIX509Cert findCertByEmailAddress(in ACString 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 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.
   */
  [must_use]
  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 Object signing
   *                    trust. The object signing trust flags are effectively
   *                    ignored by gecko, but they still must be specified (at
   *                    least by a final trailing comma) because this argument
   *                    is passed to CERT_DecodeTrustString.
   */
  [must_use]
  void setCertTrustFromString(in nsIX509Cert cert, in ACString 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.
   */
  [must_use]
  boolean isCertTrusted(in nsIX509Cert cert,
                        in unsigned long certType,
                        in unsigned long trustType);

  /**
   *  Import certificate(s) from file
   *
   *  @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.
   */
  [must_use]
  void importCertsFromFile(in nsIFile aFile,
                           in unsigned long aType);

  /**
   *  Import a PKCS#12 file containing cert(s) and key(s) into the database.
   *
   *  @param aFile Identifies a file that contains the data to be imported.
   */
  [must_use]
  void importPKCS12File(in nsIFile aFile);

  /**
   *  Export a set of certs and keys from the database to a PKCS#12 file.
   *
   *  @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.
   */
  [must_use]
  void exportPKCS12File(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.
   */
  [must_use]
  nsIX509Cert constructX509FromBase64(in ACString base64);

  /*
   *  Decode a raw data presentation and instantiate an object in memory.
   *
   *  @param certDER The raw representation of a certificate,
   *                 encoded as raw DER.
   *  @return The new certificate object.
   */
  [must_use]
  nsIX509Cert constructX509(in ACString certDER);

  /**
   *  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.
   */
  // 1 used to be AppMarketplaceProdPublicRoot.
  // 2 used to be AppMarketplaceProdReviewersRoot.
  // 3 used to be AppMarketplaceDevPublicRoot.
  // 4 used to be AppMarketplaceDevReviewersRoot.
  // 5 used to be AppMarketplaceStageRoot.
  const AppTrustedRoot AppXPCShellRoot = 6;
  const AppTrustedRoot AddonsPublicRoot = 7;
  const AppTrustedRoot AddonsStageRoot = 8;
  const AppTrustedRoot PrivilegedPackageRoot = 9;
  /*
   * If DeveloperImportedRoot is set as trusted root, a CA from local file
   * system will be imported. Only used when preference
   * "network.http.packaged-apps-developer-mode" is set.
   * The path of the CA is specified by preference
   * "network.http.packaged-apps-developer-trusted-root".
   */
  const AppTrustedRoot DeveloperImportedRoot = 10;
  [must_use]
  void openSignedAppFileAsync(in AppTrustedRoot trustedRoot,
                              in nsIFile aJarFile,
                              in nsIOpenSignedAppFileCallback callback);

  /**
   *  Verifies the signature on a directory representing an unpacked signed
   *  JAR file. To be considered valid, there must be exactly one signature
   *  on the directory structure 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 and the trusted certificate that signed the
   *  unpacked JAR are returned.
   *
   *  On failure, an error code is returned.
   */
  [must_use]
  void verifySignedDirectoryAsync(in AppTrustedRoot trustedRoot,
                                  in nsIFile aUnpackedDir,
                                  in nsIVerifySignedDirectoryCallback callback);

  /*
   * Add a cert to a cert DB from a binary string.
   *
   * @param certDER The raw DER encoding of a certificate.
   * @param trust String describing the trust settings to assign the
   *              certificate. Decoded by CERT_DecodeTrustString. Consists of 3
   *              comma separated sets of characters, indicating SSL, Email, and
   *              Object signing trust. The object signing trust flags are
   *              effectively ignored by gecko, but they still must be specified
   *              (at least by a final trailing comma) because this argument is
   *              passed to CERT_DecodeTrustString.
   * @return nsIX509Cert the resulting certificate
   */
  [must_use]
  nsIX509Cert addCert(in ACString certDER, in ACString trust);

  // 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 aHostname the (optional) hostname to verify for
   *  @param aTime the time at which to verify, in seconds since the epoch
   *  @param aVerifiedChain 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
   */
  [must_use]
  int32_t /*PRErrorCode*/
    verifyCertAtTime(in nsIX509Cert aCert,
                     in int64_t /*SECCertificateUsage*/ aUsage,
                     in uint32_t aFlags,
                     in ACString aHostname,
                     in uint64_t aTime,
                     out nsIX509CertList aVerifiedChain,
                     out bool aHasEVPolicy);
  [must_use]
  int32_t /*PRErrorCode*/
    verifyCertNow(in nsIX509Cert aCert,
                  in int64_t /*SECCertificateUsage*/ aUsage,
                  in uint32_t aFlags,
                  in ACString aHostname,
                  out nsIX509CertList aVerifiedChain,
                  out bool aHasEVPolicy);

  /**
   * Similar to the above, but asynchronous. As a result, use of this API is not
   * limited to tests.
   */
  [must_use]
  void asyncVerifyCertAtTime(in nsIX509Cert aCert,
                             in int64_t /*SECCertificateUsage*/ aUsage,
                             in uint32_t aFlags,
                             in ACString aHostname,
                             in uint64_t aTime,
                             in nsICertVerificationCallback aCallback);

  // Clears the OCSP cache for the current certificate verification
  // implementation.
  [must_use]
  void clearOCSPCache();

  /*
   * Add a cert to a cert DB from a base64 encoded string.
   *
   * @param base64 The raw representation of a certificate, encoded as Base 64.
   * @param trust String describing the trust settings to assign the
   *              certificate. Decoded by CERT_DecodeTrustString. Consists of 3
   *              comma separated sets of characters, indicating SSL, Email, and
   *              Object signing trust. The object signing trust flags are
   *              effectively ignored by gecko, but they still must be specified
   *              (at least by a final trailing comma) because this argument is
   *              passed to CERT_DecodeTrustString.
   * @return nsIX509Cert the resulting certificate
   */
  [must_use]
  nsIX509Cert addCertFromBase64(in ACString base64, in ACString trust);

  /*
   * Get all the known certs in the database
   */
  [must_use]
  nsIX509CertList getCerts();

  /*
   * Get a list of imported enterprise root certificates (currently only
   * implemented on Windows).
   */
  [must_use]
  nsIX509CertList getEnterpriseRoots();
};