summaryrefslogtreecommitdiffstats
path: root/security/manager/ssl/nsIX509CertDB.idl
blob: 733caed3d6c3e926ba04d9a27dbab61459cadb6a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIArray;
interface nsIX509Cert;
interface nsIFile;
interface nsIInterfaceRequestor;
interface nsIZipReader;
interface nsIInputStream;

%{C++
#define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1"
%}

typedef uint32_t AppTrustedRoot;

[scriptable, builtinclass, uuid(e5795418-86e0-4c0b-9b98-ac7eee0c2af7)]
interface nsIAppSignatureInfo : nsISupports {
  // Supported signature algorithms.
  cenum SignatureAlgorithm : 32 {
    PKCS7_WITH_SHA1,
    PKCS7_WITH_SHA256,
    COSE_WITH_SHA256,
  };

  // The certificate that created the signature.
  readonly attribute nsIX509Cert signerCert;
  readonly attribute nsIAppSignatureInfo_SignatureAlgorithm signatureAlgorithm;
};

[scriptable, function, uuid(fc2b60e5-9a07-47c2-a2cd-b83b68a660ac)]
interface nsIOpenSignedAppFileCallback : nsISupports
{
  void openSignedAppFileFinished(in nsresult rv,
                                 in nsIZipReader aZipReader,
                                 in Array<nsIAppSignatureInfo> aSignatureInfos);
};

[scriptable, function, uuid(07c08655-8b11-4650-b6c4-0c145595ceb5)]
interface nsIAsyncBoolCallback : nsISupports
{
    void onResult(in bool result);
};

/**
 * Callback type for use with asyncVerifyCertAtTime.
 * If aPRErrorCode is PRErrorCodeSuccess (i.e. 0), aVerifiedChain represents the
 * verified certificate chain determined by asyncVerifyCertAtTime. aHasEVPolicy
 * represents whether or not the end-entity certificate verified as EV.
 * If aPRErrorCode is non-zero, it represents the error encountered during
 * verification. aVerifiedChain is null in that case and aHasEVPolicy has no
 * meaning.
 */
[scriptable, function, uuid(49e16fc8-efac-4f57-8361-956ef6b960a4)]
interface nsICertVerificationCallback : nsISupports {
  void verifyCertFinished(in int32_t aPRErrorCode,
                          in Array<nsIX509Cert> aVerifiedChain,
                          in bool aHasEVPolicy);
};

/**
 * This represents a service to access and manipulate
 * X.509 certificates stored in a database.
 */
[scriptable, uuid(5c16cd9b-5a73-47f1-ab0f-11ede7495cce)]
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;

  /**
   *  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.
   */
  [must_use]
  nsIX509Cert findCertByDBKey(in ACString aDBkey);

  /**
   *  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 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.
   */
  [must_use]
  void setCertTrust(in nsIX509Cert cert,
                    in unsigned long type,
                    in unsigned long trust);

  /**
   * @param cert        The certificate for which to modify trust.
   * @param trustString decoded by CERT_DecodeTrustString. 3 comma separated
   *                    characters, indicating SSL, Email, and Object signing
   *                    trust. The object signing trust flags are effectively
   *                    ignored by gecko, but they still must be specified (at
   *                    least by a final trailing comma) because this argument
   *                    is passed to CERT_DecodeTrustString.
   */
  [must_use]
  void setCertTrustFromString(in nsIX509Cert cert, in ACString trustString);

  /**
   *  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.
   */
  [must_use]
  boolean isCertTrusted(in nsIX509Cert cert,
                        in unsigned long certType,
                        in unsigned long trustType);

  /**
   *  Import certificate(s) from file
   *
   *  @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.
   */
  [must_use]
  void importCertsFromFile(in nsIFile aFile,
                           in unsigned long aType);

  const uint32_t Success = 0;
  const uint32_t ERROR_UNKNOWN = 1;
  const uint32_t ERROR_PKCS12_NOSMARTCARD_EXPORT = 2;
  const uint32_t ERROR_PKCS12_RESTORE_FAILED = 3;
  const uint32_t ERROR_PKCS12_BACKUP_FAILED = 4;
  const uint32_t ERROR_PKCS12_CERT_COLLISION = 5;
  const uint32_t ERROR_BAD_PASSWORD = 6;
  const uint32_t ERROR_DECODE_ERROR = 7;
  const uint32_t ERROR_PKCS12_DUPLICATE_DATA = 8;

  /**
   *  Import a PKCS#12 file containing cert(s) and key(s) into the database.
   *
   *  @param aFile Identifies a file that contains the data to be imported.
   *  @param password The password used to protect the file.
   *  @return Success or the specific error code on failure.  The return
   *          values are defined in this file.
   */
  [must_use]
  uint32_t importPKCS12File(in nsIFile aFile, in AString aPassword);

  /**
   *  Export a set of certs and keys from the database to a PKCS#12 file.
   *
   *  @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.
   *  @param password The password used to protect the file.
   *  @return Success or the specific error code on failure
   */
  [must_use]
  uint32_t exportPKCS12File(in nsIFile aFile,
                            in Array<nsIX509Cert> aCerts,
                            in AString aPassword);

  /*
   *  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.
   */
  [must_use]
  nsIX509Cert constructX509FromBase64(in ACString base64);

  /*
   *  Decode a raw data presentation and instantiate an object in memory.
   *
   *  @param certDER The raw representation of a certificate,
   *                 encoded as raw DER.
   *  @return The new certificate object.
   */
  [must_use]
  nsIX509Cert constructX509(in Array<uint8_t> certDER);

  /**
   *  Verifies the signature on the given JAR file to verify that it has a
   *  valid signature.  To be considered valid, there must be exactly one
   *  signature on the JAR file and that signature must have signed every
   *  entry. Further, the signature must come from a certificate that
   *  is trusted for code signing.
   *
   *  On success, NS_OK, a nsIZipReader, and the trusted certificate that
   *  signed the JAR are returned.
   *
   *  On failure, an error code is returned.
   *
   *  This method returns a nsIZipReader, instead of taking an nsIZipReader
   *  as input, to encourage users of the API to verify the signature as the
   *  first step in opening the JAR.
   */
  // 1 used to be AppMarketplaceProdPublicRoot.
  // 2 used to be AppMarketplaceProdReviewersRoot.
  // 3 used to be AppMarketplaceDevPublicRoot.
  // 4 used to be AppMarketplaceDevReviewersRoot.
  // 5 used to be AppMarketplaceStageRoot.
  const AppTrustedRoot AppXPCShellRoot = 6;
  const AppTrustedRoot AddonsPublicRoot = 7;
  const AppTrustedRoot AddonsStageRoot = 8;
  [must_use]
  void openSignedAppFileAsync(in AppTrustedRoot trustedRoot,
                              in nsIFile aJarFile,
                              in nsIOpenSignedAppFileCallback callback);

  /*
   * Add a cert to a cert DB from a binary string.
   *
   * @param certDER The raw DER encoding of a certificate.
   * @param trust String describing the trust settings to assign the
   *              certificate. Decoded by CERT_DecodeTrustString. Consists of 3
   *              comma separated sets of characters, indicating SSL, Email, and
   *              Object signing trust. The object signing trust flags are
   *              effectively ignored by gecko, but they still must be specified
   *              (at least by a final trailing comma) because this argument is
   *              passed to CERT_DecodeTrustString.
   * @return nsIX509Cert the resulting certificate
   */
  [must_use]
  nsIX509Cert addCert(in ACString certDER, in ACString trust);

  // Flags for asyncVerifyCertAtTime (these must match the values in
  // CertVerifier.cpp):
  // Prevent network traffic.
  const uint32_t FLAG_LOCAL_ONLY = 1 << 0;
  // Do not fall back to DV verification after attempting EV validation.
  const uint32_t FLAG_MUST_BE_EV = 1 << 1;

  /*
   * Asynchronously verify a certificate given a set of parameters. Calls the
   * `verifyCertFinished` function on the provided `nsICertVerificationCallback`
   * with the results of the verification operation.
   * See the documentation for  nsICertVerificationCallback.
   *
   * @param aCert the certificate to verify
   * @param aUsage an integer representing the usage to verify for (see
   *               SECCertificateUsage in certt.h from NSS)
   * @param aFlags flags as described above
   * @param aHostname the (optional) hostname to verify for
   * @param aTime the time at which to verify, in seconds since the epoch
   * @param aCallback the nsICertVerificationCallback that will receive the
                      results of this verification
   * @return a succeeding nsresult if the job was dispatched successfully
   */
  [must_use]
  void asyncVerifyCertAtTime(in nsIX509Cert aCert,
                             in int64_t /*SECCertificateUsage*/ aUsage,
                             in uint32_t aFlags,
                             in ACString aHostname,
                             in uint64_t aTime,
                             in nsICertVerificationCallback aCallback);

  // Clears the OCSP cache for the current certificate verification
  // implementation.
  [must_use]
  void clearOCSPCache();

  /*
   * Add a cert to a cert DB from a base64 encoded string.
   *
   * @param base64 The raw representation of a certificate, encoded as Base 64.
   * @param trust String describing the trust settings to assign the
   *              certificate. Decoded by CERT_DecodeTrustString. Consists of 3
   *              comma separated sets of characters, indicating SSL, Email, and
   *              Object signing trust. The object signing trust flags are
   *              effectively ignored by gecko, but they still must be specified
   *              (at least by a final trailing comma) because this argument is
   *              passed to CERT_DecodeTrustString.
   * @return nsIX509Cert the resulting certificate
   */
  [must_use]
  nsIX509Cert addCertFromBase64(in ACString base64, in ACString trust);

  /*
   * Get all the known certs in the database
   */
  [must_use]
  Array<nsIX509Cert> getCerts();

  /**
   * Encode the list of certificates as a PKCS#7 SignedData structure. No data
   * is actually signed - this is merely a way of exporting a collection of
   * certificates.
   */
  [must_use]
  ACString asPKCS7Blob(in Array<nsIX509Cert> certList);

  /**
   * Iterates through all the certs and returns false if any of the trusted
   * CA certs are not built-in roots; and true otherwise.
   */
  [must_use]
  void asyncHasThirdPartyRoots(in nsIAsyncBoolCallback callback);
};