/gecko_sdk/idl/nsIX509CertDB.idl
IDL | 300 lines | 58 code | 25 blank | 217 comment | 0 complexity | d7b2ab9ed1aa0ca03aa06e6d03ce2a64 MD5 | raw file
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