Version 1.8 of gecko-sdk. Downloaded from here:...

gecko-sdk/idl/nsIX509CertDB.idl

+/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ *
+ * ***** BEGIN LICENSE BLOCK *****
+ * Version: MPL 1.1/GPL 2.0/LGPL 2.1
+ *
+ * The contents of this file are subject to the Mozilla Public License Version
+ * 1.1 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ * http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+ * for the specific language governing rights and limitations under the
+ * License.
+ *
+ * The Original Code is mozilla.org code.
+ *
+ * The Initial Developer of the Original Code is
+ * Netscape Communications Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 1998
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ *   Javier Delgadillo <javi@netscape.com>
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * either the GNU General Public License Version 2 or later (the "GPL"), or
+ * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
+ * in which case the provisions of the GPL or the LGPL are applicable instead
+ * of those above. If you wish to allow use of your version of this file only
+ * under the terms of either the GPL or the LGPL, and not to allow others to
+ * use your version of this file under the terms of the MPL, indicate your
+ * decision by deleting the provisions above and replace them with the notice
+ * and other provisions required by the GPL or the LGPL. If you do not delete
+ * the provisions above, a recipient may use your version of this file under
+ * the terms of any one of the MPL, the GPL or the LGPL.
+ *
+ * ***** END LICENSE BLOCK ***** */
+
+#include "nsISupports.idl"
+
+interface nsIArray;
+interface nsIX509Cert;
+interface nsILocalFile;
+interface nsIInterfaceRequestor;
+
+%{C++
+#define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1"
+%}
+
+/**
+ * This represents a service to access and manipulate 
+ * X.509 certificates stored in a database.
+ *
+ * @status FROZEN
+ */
+[scriptable, uuid(da48b3c0-1284-11d5-ac67-000064657374)]
+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 the 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 the 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 nsILocalFile 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 nsILocalFile 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 nsILocalFile aFile,
+                        in unsigned long count,
+                        [array, size_is(count)] in nsIX509Cert aCerts);
+
+  /**
+   *  An array of all known OCSP responders within the scope of the 
+   *  certificate database.
+   *
+   *  @return Array of OCSP responders, entries are QIable to nsIOCSPResponder.
+   */
+  nsIArray getOCSPResponders();
+
+  /**
+   *  Whether OCSP is enabled in preferences.
+   */
+  readonly attribute boolean isOcspOn;
+
+  /*
+   *  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);
+};
+