/* -*- 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;

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

[scriptable, function, uuid(48411e2d-85a9-4b16-bec8-e30cde801f9e)]
interface nsIOpenSignedJARFileCallback : nsISupports
{
  void openSignedJARFileFinished(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(ab0a1c52-f7fd-4fe7-9e65-7d3705a8580e)]
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);

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

  /*
   *  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.
   */
  void openSignedJARFileAsync(in nsIFile aJarFile,
                              in nsIOpenSignedJARFileCallback 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);
};