gecko/security/manager/ssl/public/nsIX509CertDB.idl
Mitchell Field eb1e793da7 Remove @status FROZEN and @status UNDER_REVIEW. r=bsmedberg
--HG--
extra : rebase_source : 7fab31a6b7898e05ff828482390846cc9ce2854d
2010-07-02 10:27:06 -04:00

299 lines
11 KiB
Plaintext

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