security/manager/ssl/public/nsIX509CertDB.idl@141e0f1194b1
security/manager/ssl/public/nsIX509CertDB.idl
Wed, 31 Dec 2014 07:16:47 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:16:47 +0100
- branch
- TOR_BUG_9701
- changeset 3
- 141e0f1194b1
- permissions
- -rw-r--r--
Revert simplistic fix pending revisit of Mozilla integration attempt.
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include "nsISupports.idl"
9 interface nsIArray;
10 interface nsIX509Cert;
11 interface nsIX509Cert3;
12 interface nsIFile;
13 interface nsIInterfaceRequestor;
14 interface nsIZipReader;
15 interface nsIRecentBadCerts;
16 interface nsIX509CertList;
18 %{C++
19 #define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1"
20 %}
22 typedef uint32_t AppTrustedRoot;
24 [scriptable, function, uuid(0927baea-622d-4e41-a76d-255af426e7fb)]
25 interface nsIOpenSignedAppFileCallback : nsISupports
26 {
27 void openSignedAppFileFinished(in nsresult rv,
28 in nsIZipReader aZipReader,
29 in nsIX509Cert3 aSignerCert);
30 };
32 /**
33 * This represents a service to access and manipulate
34 * X.509 certificates stored in a database.
35 */
36 [scriptable, uuid(7446a5b1-84ca-491f-a2fe-0bc60a71ffa5)]
37 interface nsIX509CertDB : nsISupports {
39 /**
40 * Constants that define which usages a certificate
41 * is trusted for.
42 */
43 const unsigned long UNTRUSTED = 0;
44 const unsigned long TRUSTED_SSL = 1 << 0;
45 const unsigned long TRUSTED_EMAIL = 1 << 1;
46 const unsigned long TRUSTED_OBJSIGN = 1 << 2;
48 /**
49 * Given a nickname and optionally a token,
50 * locate the matching certificate.
51 *
52 * @param aToken Optionally limits the scope of
53 * this function to a token device.
54 * Can be null to mean any token.
55 * @param aNickname The nickname to be used as the key
56 * to find a certificate.
57 *
58 * @return The matching certificate if found.
59 */
60 nsIX509Cert findCertByNickname(in nsISupports aToken,
61 in AString aNickname);
63 /**
64 * Will find a certificate based on its dbkey
65 * retrieved by getting the dbKey attribute of
66 * the certificate.
67 *
68 * @param aDBkey Database internal key, as obtained using
69 * attribute dbkey in nsIX509Cert.
70 * @param aToken Optionally limits the scope of
71 * this function to a token device.
72 * Can be null to mean any token.
73 */
74 nsIX509Cert findCertByDBKey(in string aDBkey, in nsISupports aToken);
76 /**
77 * Obtain a list of certificate nicknames from the database.
78 * What the name is depends on type:
79 * user, ca, or server cert - the nickname
80 * email cert - the email address
81 *
82 * @param aToken Optionally limits the scope of
83 * this function to a token device.
84 * Can be null to mean any token.
85 * @param aType Type of certificate to obtain
86 * See certificate type constants in nsIX509Cert.
87 * @param count The number of nicknames in the returned array
88 * @param certNameList The returned array of certificate nicknames.
89 */
90 void findCertNicknames(in nsISupports aToken,
91 in unsigned long aType,
92 out unsigned long count,
93 [array, size_is(count)] out wstring certNameList);
95 /**
96 * Find user's own email encryption certificate by nickname.
97 *
98 * @param aNickname The nickname to be used as the key
99 * to find the certificate.
100 *
101 * @return The matching certificate if found.
102 */
103 nsIX509Cert findEmailEncryptionCert(in AString aNickname);
105 /**
106 * Find user's own email signing certificate by nickname.
107 *
108 * @param aNickname The nickname to be used as the key
109 * to find the certificate.
110 *
111 * @return The matching certificate if found.
112 */
113 nsIX509Cert findEmailSigningCert(in AString aNickname);
115 /**
116 * Find a certificate by email address.
117 *
118 * @param aToken Optionally limits the scope of
119 * this function to a token device.
120 * Can be null to mean any token.
121 * @param aEmailAddress The email address to be used as the key
122 * to find the certificate.
123 *
124 * @return The matching certificate if found.
125 */
126 nsIX509Cert findCertByEmailAddress(in nsISupports aToken,
127 in string aEmailAddress);
129 /**
130 * Use this to import a stream sent down as a mime type into
131 * the certificate database on the default token.
132 * The stream may consist of one or more certificates.
133 *
134 * @param data The raw data to be imported
135 * @param length The length of the data to be imported
136 * @param type The type of the certificate, see constants in nsIX509Cert
137 * @param ctx A UI context.
138 */
139 void importCertificates([array, size_is(length)] in octet data,
140 in unsigned long length,
141 in unsigned long type,
142 in nsIInterfaceRequestor ctx);
144 /**
145 * Import another person's email certificate into the database.
146 *
147 * @param data The raw data to be imported
148 * @param length The length of the data to be imported
149 * @param ctx A UI context.
150 */
151 void importEmailCertificate([array, size_is(length)] in octet data,
152 in unsigned long length,
153 in nsIInterfaceRequestor ctx);
155 /**
156 * Import a server machine's certificate into the database.
157 *
158 * @param data The raw data to be imported
159 * @param length The length of the data to be imported
160 * @param ctx A UI context.
161 */
162 void importServerCertificate([array, size_is(length)] in octet data,
163 in unsigned long length,
164 in nsIInterfaceRequestor ctx);
166 /**
167 * Import a personal certificate into the database, assuming
168 * the database already contains the private key for this certificate.
169 *
170 * @param data The raw data to be imported
171 * @param length The length of the data to be imported
172 * @param ctx A UI context.
173 */
174 void importUserCertificate([array, size_is(length)] in octet data,
175 in unsigned long length,
176 in nsIInterfaceRequestor ctx);
178 /**
179 * Delete a certificate stored in the database.
180 *
181 * @param aCert Delete this certificate.
182 */
183 void deleteCertificate(in nsIX509Cert aCert);
185 /**
186 * Modify the trust that is stored and associated to a certificate within
187 * a database. Separate trust is stored for
188 * One call manipulates the trust for one trust type only.
189 * See the trust type constants defined within this interface.
190 *
191 * @param cert Change the stored trust of this certificate.
192 * @param type The type of the certificate. See nsIX509Cert.
193 * @param trust A bitmask. The new trust for the possible usages.
194 * See the trust constants defined within this interface.
195 */
196 void setCertTrust(in nsIX509Cert cert,
197 in unsigned long type,
198 in unsigned long trust);
200 /**
201 * @param cert The certificate for which to modify trust.
202 * @param trustString decoded by CERT_DecodeTrustString. 3 comma separated
203 * characters, indicating SSL, Email, and Obj signing
204 * trust.
205 */
206 void setCertTrustFromString(in nsIX509Cert3 cert, in string trustString);
208 /**
209 * Query whether a certificate is trusted for a particular use.
210 *
211 * @param cert Obtain the stored trust of this certificate.
212 * @param certType The type of the certificate. See nsIX509Cert.
213 * @param trustType A single bit from the usages constants defined
214 * within this interface.
215 *
216 * @return Returns true if the certificate is trusted for the given use.
217 */
218 boolean isCertTrusted(in nsIX509Cert cert,
219 in unsigned long certType,
220 in unsigned long trustType);
222 /**
223 * Import certificate(s) from file
224 *
225 * @param aToken Optionally limits the scope of
226 * this function to a token device.
227 * Can be null to mean any token.
228 * @param aFile Identifies a file that contains the certificate
229 * to be imported.
230 * @param aType Describes the type of certificate that is going to
231 * be imported. See type constants in nsIX509Cert.
232 */
233 void importCertsFromFile(in nsISupports aToken,
234 in nsIFile aFile,
235 in unsigned long aType);
237 /**
238 * Import a PKCS#12 file containing cert(s) and key(s) into the database.
239 *
240 * @param aToken Optionally limits the scope of
241 * this function to a token device.
242 * Can be null to mean any token.
243 * @param aFile Identifies a file that contains the data
244 * to be imported.
245 */
246 void importPKCS12File(in nsISupports aToken,
247 in nsIFile aFile);
249 /**
250 * Export a set of certs and keys from the database to a PKCS#12 file.
251 *
252 * @param aToken Optionally limits the scope of
253 * this function to a token device.
254 * Can be null to mean any token.
255 * @param aFile Identifies a file that will be filled with the data
256 * to be exported.
257 * @param count The number of certificates to be exported.
258 * @param aCerts The array of all certificates to be exported.
259 */
260 void exportPKCS12File(in nsISupports aToken,
261 in nsIFile aFile,
262 in unsigned long count,
263 [array, size_is(count)] in nsIX509Cert aCerts);
265 /*
266 * Decode a raw data presentation and instantiate an object in memory.
267 *
268 * @param base64 The raw representation of a certificate,
269 * encoded as Base 64.
270 * @return The new certificate object.
271 */
272 nsIX509Cert constructX509FromBase64(in string base64);
274 /*
275 * Decode a raw data presentation and instantiate an object in memory.
276 *
277 * @param certDER The raw representation of a certificate,
278 * encoded as raw DER.
279 * @param length The length of the DER string.
280 * @return The new certificate object.
281 */
282 nsIX509Cert constructX509(in string certDER, in unsigned long length);
284 /*
285 * Obtain a reference to the appropriate service for recent
286 * bad certificates. May only be called on the main thread.
287 *
288 * @param isPrivate True if the service for certs for private connections
289 * is desired, false otherwise.
290 * @return The requested service.
291 */
292 nsIRecentBadCerts getRecentBadCerts(in boolean isPrivate);
294 /**
295 * Verifies the signature on the given JAR file to verify that it has a
296 * valid signature. To be considered valid, there must be exactly one
297 * signature on the JAR file and that signature must have signed every
298 * entry. Further, the signature must come from a certificate that
299 * is trusted for code signing.
300 *
301 * On success, NS_OK, a nsIZipReader, and the trusted certificate that
302 * signed the JAR are returned.
303 *
304 * On failure, an error code is returned.
305 *
306 * This method returns a nsIZipReader, instead of taking an nsIZipReader
307 * as input, to encourage users of the API to verify the signature as the
308 * first step in opening the JAR.
309 */
310 const AppTrustedRoot AppMarketplaceProdPublicRoot = 1;
311 const AppTrustedRoot AppMarketplaceProdReviewersRoot = 2;
312 const AppTrustedRoot AppMarketplaceDevPublicRoot = 3;
313 const AppTrustedRoot AppMarketplaceDevReviewersRoot = 4;
314 const AppTrustedRoot AppXPCShellRoot = 5;
315 void openSignedAppFileAsync(in AppTrustedRoot trustedRoot,
316 in nsIFile aJarFile,
317 in nsIOpenSignedAppFileCallback callback);
319 /*
320 * Add a cert to a cert DB from a binary string.
321 *
322 * @param certDER The raw DER encoding of a certificate.
323 * @param aTrust decoded by CERT_DecodeTrustString. 3 comma separated characters,
324 * indicating SSL, Email, and Obj signing trust
325 * @param aName name of the cert for display purposes.
326 */
327 void addCert(in ACString certDER, in string aTrust, in string aName);
329 // Flags for verifyCertNow (these must match the values in CertVerifier.cpp):
330 // Prevent network traffic. Doesn't work with classic verification.
331 const uint32_t FLAG_LOCAL_ONLY = 1 << 0;
332 // Do not fall back to DV verification after attempting EV validation.
333 // Actually does prevent network traffic, but can cause a valid EV
334 // certificate to not be considered valid.
335 const uint32_t FLAG_MUST_BE_EV = 1 << 1;
337 /** Warning: This interface is inteded to use only for testing only as:
338 * 1. It can create IO on the main thread.
339 * 2. It is in constant change, so in/out can change at any release.
340 *
341 * Obtain the verification result for a cert given a particular usage.
342 * On success, the call returns 0, the chain built during verification,
343 * and whether the cert is good for EV usage.
344 * On failure, the call returns the PRErrorCode for the verification failure
345 *
346 * @param aCert Obtain the stored trust of this certificate
347 * @param aUsage a integer representing the usage from NSS
348 * @param aFlags flags as described above
349 * @param verifedChain chain of verification up to the root if success
350 * @param aHasEVPolicy bool that signified that the cert was an EV cert
351 * @return 0 if success or the value or the error code for the verification
352 * failure
353 */
354 int32_t /*PRErrorCode*/
355 verifyCertNow(in nsIX509Cert aCert,
356 in int64_t /*SECCertificateUsage*/ aUsage,
357 in uint32_t aFlags,
358 out nsIX509CertList verifiedChain,
359 out bool aHasEVPolicy);
361 // Clears the OCSP cache for the current certificate verification
362 // implementation.
363 void clearOCSPCache();
364 };
