/gecko_sdk/idl/nsIX509CertDB.idl

  1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2 *
  3 * ***** BEGIN LICENSE BLOCK *****
  4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5 *
  6 * The contents of this file are subject to the Mozilla Public License Version
  7 * 1.1 (the "License"); you may not use this file except in compliance with
  8 * the License. You may obtain a copy of the License at
  9 * http://www.mozilla.org/MPL/
 10 *
 11 * Software distributed under the License is distributed on an "AS IS" basis,
 12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 13 * for the specific language governing rights and limitations under the
 14 * License.
 15 *
 16 * The Original Code is mozilla.org code.
 17 *
 18 * The Initial Developer of the Original Code is
 19 * Netscape Communications Corporation.
 20 * Portions created by the Initial Developer are Copyright (C) 1998
 21 * the Initial Developer. All Rights Reserved.
 22 *
 23 * Contributor(s):
 24 *   Javier Delgadillo <javi@netscape.com>
 25 *
 26 * Alternatively, the contents of this file may be used under the terms of
 27 * either the GNU General Public License Version 2 or later (the "GPL"), or
 28 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 29 * in which case the provisions of the GPL or the LGPL are applicable instead
 30 * of those above. If you wish to allow use of your version of this file only
 31 * under the terms of either the GPL or the LGPL, and not to allow others to
 32 * use your version of this file under the terms of the MPL, indicate your
 33 * decision by deleting the provisions above and replace them with the notice
 34 * and other provisions required by the GPL or the LGPL. If you do not delete
 35 * the provisions above, a recipient may use your version of this file under
 36 * the terms of any one of the MPL, the GPL or the LGPL.
 37 *
 38 * ***** END LICENSE BLOCK ***** */
 39
 40#include "nsISupports.idl"
 41
 42interface nsIArray;
 43interface nsIX509Cert;
 44interface nsILocalFile;
 45interface nsIInterfaceRequestor;
 46
 47%{C++
 48#define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1"
 49%}
 50
 51/**
 52 * This represents a service to access and manipulate 
 53 * X.509 certificates stored in a database.
 54 *
 55 * @status FROZEN
 56 */
 57[scriptable, uuid(da48b3c0-1284-11d5-ac67-000064657374)]
 58interface nsIX509CertDB : nsISupports {
 59
 60  /**
 61   *  Constants that define which usages a certificate
 62   *  is trusted for.
 63   */
 64  const unsigned long UNTRUSTED       =      0;
 65  const unsigned long TRUSTED_SSL     = 1 << 0;
 66  const unsigned long TRUSTED_EMAIL   = 1 << 1;
 67  const unsigned long TRUSTED_OBJSIGN = 1 << 2;
 68
 69  /**
 70   *  Given a nickname and optionally a token,
 71   *  locate the matching certificate.
 72   *
 73   *  @param aToken Optionally limits the scope of 
 74   *                this function to a token device.
 75   *                Can be null to mean any token.
 76   *  @param aNickname The nickname to be used as the key
 77   *                   to find a certificate.
 78   *                
 79   *  @return The matching certificate if found.
 80   */
 81  nsIX509Cert findCertByNickname(in nsISupports aToken,
 82                                 in AString aNickname);
 83
 84  /**
 85   *  Will find a certificate based on its dbkey
 86   *  retrieved by getting the dbKey attribute of
 87   *  the certificate.
 88   *
 89   *  @param aDBkey Database internal key, as obtained using
 90   *                attribute dbkey in nsIX509Cert.
 91   *  @param aToken Optionally limits the scope of 
 92   *                this function to a token device.
 93   *                Can be null to mean any token.
 94   */
 95  nsIX509Cert findCertByDBKey(in string aDBkey, in nsISupports aToken);
 96
 97  /**
 98   *  Obtain a list of certificate nicknames from the database.
 99   *  What the name is depends on type:
100   *    user, ca, or server cert - the nickname
101   *    email cert - the email address
102   *
103   *  @param aToken Optionally limits the scope of 
104   *                this function to a token device.
105   *                Can be null to mean any token.
106   *  @param aType Type of certificate to obtain
107   *               See certificate type constants in nsIX509Cert.
108   *  @param count The number of nicknames in the returned array
109   *  @param certNameList The returned array of certificate nicknames.
110   */
111  void findCertNicknames(in nsISupports aToken, 
112                         in unsigned long aType,
113                         out unsigned long count,
114                         [array, size_is(count)] out wstring certNameList);
115
116  /**
117   *  Find the email encryption certificate by nickname.
118   *
119   *  @param aNickname The nickname to be used as the key
120   *                   to find the certificate.
121   *                
122   *  @return The matching certificate if found.
123   */
124  nsIX509Cert findEmailEncryptionCert(in AString aNickname);
125
126  /**
127   *  Find the email signing certificate by nickname.
128   *
129   *  @param aNickname The nickname to be used as the key
130   *                   to find the certificate.
131   *                
132   *  @return The matching certificate if found.
133   */
134  nsIX509Cert findEmailSigningCert(in AString aNickname);
135
136  /**
137   *  Find a certificate by email address.
138   *
139   *  @param aToken Optionally limits the scope of 
140   *                this function to a token device.
141   *                Can be null to mean any token.
142   *  @param aEmailAddress The email address to be used as the key
143   *                       to find the certificate.
144   *                
145   *  @return The matching certificate if found.
146   */
147  nsIX509Cert findCertByEmailAddress(in nsISupports aToken,
148                                     in string aEmailAddress);
149
150  /**
151   *  Use this to import a stream sent down as a mime type into
152   *  the certificate database on the default token.
153   *  The stream may consist of one or more certificates.
154   *
155   *  @param data The raw data to be imported
156   *  @param length The length of the data to be imported
157   *  @param type The type of the certificate, see constants in nsIX509Cert
158   *  @param ctx A UI context.
159   */
160  void importCertificates([array, size_is(length)] in octet data,
161                          in unsigned long length,
162                          in unsigned long type,
163                          in nsIInterfaceRequestor ctx);
164
165  /**
166   *  Import another person's email certificate into the database.
167   *
168   *  @param data The raw data to be imported
169   *  @param length The length of the data to be imported
170   *  @param ctx A UI context.
171   */
172  void importEmailCertificate([array, size_is(length)] in octet data,
173                              in unsigned long length,
174                              in nsIInterfaceRequestor ctx);
175
176  /**
177   *  Import a server machine's certificate into the database.
178   *
179   *  @param data The raw data to be imported
180   *  @param length The length of the data to be imported
181   *  @param ctx A UI context.
182   */
183  void importServerCertificate([array, size_is(length)] in octet data,
184                               in unsigned long length,
185                               in nsIInterfaceRequestor ctx);
186
187  /**
188   *  Import a personal certificate into the database, assuming 
189   *  the database already contains the private key for this certificate.
190   *
191   *  @param data The raw data to be imported
192   *  @param length The length of the data to be imported
193   *  @param ctx A UI context.
194   */
195  void importUserCertificate([array, size_is(length)] in octet data,
196                             in unsigned long length,
197                             in nsIInterfaceRequestor ctx);
198
199  /**
200   *  Delete a certificate stored in the database.
201   *
202   *  @param aCert Delete this certificate.
203   */
204  void deleteCertificate(in nsIX509Cert aCert);
205
206  /**
207   *  Modify the trust that is stored and associated to a certificate within
208   *  a database. Separate trust is stored for 
209   *  One call manipulates the trust for one trust type only.
210   *  See the trust type constants defined within this interface.
211   *
212   *  @param cert Change the stored trust of this certificate.
213   *  @param type The type of the certificate. See nsIX509Cert.
214   *  @param trust A bitmask. The new trust for the possible usages.
215   *               See the trust constants defined within this interface.
216   */
217  void setCertTrust(in nsIX509Cert cert,
218                    in unsigned long type,
219                    in unsigned long trust);
220
221  /**
222   *  Query whether a certificate is trusted for a particular use.
223   *
224   *  @param cert Obtain the stored trust of this certificate.
225   *  @param certType The type of the certificate. See nsIX509Cert.
226   *  @param trustType A single bit from the usages constants defined 
227   *                   within this interface.
228   *
229   *  @return Returns true if the certificate is trusted for the given use.
230   */
231  boolean isCertTrusted(in nsIX509Cert cert,
232                       in unsigned long certType,
233                       in unsigned long trustType);
234
235  /**
236   *  Import certificate(s) from file
237   *
238   *  @param aToken Optionally limits the scope of 
239   *                this function to a token device.
240   *                Can be null to mean any token.
241   *  @param aFile Identifies a file that contains the certificate
242   *               to be imported.
243   *  @param aType Describes the type of certificate that is going to
244   *               be imported. See type constants in nsIX509Cert.
245   */
246  void importCertsFromFile(in nsISupports aToken,
247                         in nsILocalFile aFile,
248                         in unsigned long aType);
249
250  /**
251   *  Import a PKCS#12 file containing cert(s) and key(s) into the database.
252   *
253   *  @param aToken Optionally limits the scope of 
254   *                this function to a token device.
255   *                Can be null to mean any token.
256   *  @param aFile Identifies a file that contains the data
257   *               to be imported.
258   */
259  void importPKCS12File(in nsISupports aToken,
260                        in nsILocalFile aFile);
261
262  /**
263   *  Export a set of certs and keys from the database to a PKCS#12 file.
264   *
265   *  @param aToken Optionally limits the scope of 
266   *                this function to a token device.
267   *                Can be null to mean any token.
268   *  @param aFile Identifies a file that will be filled with the data
269   *               to be exported.
270   *  @param count The number of certificates to be exported.
271   *  @param aCerts The array of all certificates to be exported.
272   */
273  void exportPKCS12File(in nsISupports aToken,
274                        in nsILocalFile aFile,
275                        in unsigned long count,
276                        [array, size_is(count)] in nsIX509Cert aCerts);
277
278  /**
279   *  An array of all known OCSP responders within the scope of the 
280   *  certificate database.
281   *
282   *  @return Array of OCSP responders, entries are QIable to nsIOCSPResponder.
283   */
284  nsIArray getOCSPResponders();
285
286  /**
287   *  Whether OCSP is enabled in preferences.
288   */
289  readonly attribute boolean isOcspOn;
290
291  /*
292   *  Decode a raw data presentation and instantiate an object in memory.
293   *
294   *  @param base64 The raw representation of a certificate,
295   *                encoded as Base 64.
296   *  @return The new certificate object.
297   */
298  nsIX509Cert constructX509FromBase64(in string base64);
299};
300