1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include
"nsISupports.idl"
7 #include
"nsIVariant.idl"
10 #define NS_CERTSTORAGE_CONTRACTID
"@mozilla.org/security/certstorage;1"
14 * Callback type used to notify callers that an operation performed by
15 * nsICertStorage has completed. Indicates the result of the requested
16 * operation, as well as any data returned by the operation.
18 [scriptable
, function
, uuid(3f8fe26a
-a436
-4ad4
-9c1c
-a53c60973c31
)]
19 interface nsICertStorageCallback
: nsISupports
{
21 void done
(in nsresult rv
, in nsIVariant result
);
25 * A base interface for representing the revocation state of a certificate.
26 * Implementing this interface by itself is insufficient; your type must
27 * implement an inheriting interface that specifies the certificate by issuer
28 * and serial number or by subject and public key hash.
29 * Set state to nsICertStorage.STATE_UNSET to mark the certificate as not revoked.
30 * Set state to nsICertStorage.STATE_ENFORCE to mark the certificate as revoked.
32 [scriptable
, uuid(96db6fd7
-6b64
-4a5a
-955d
-310bd9ca4234
)]
33 interface nsIRevocationState
: nsISupports
{
34 readonly attribute
short state
;
38 * An interface representing the revocation state of a certificate by issuer
39 * and serial number. Both issuer name and serial number are base64-encoded.
41 [scriptable
, uuid(23ce3546
-f1b9
-46f6
-8de3
-77704da5702f
)]
42 interface nsIIssuerAndSerialRevocationState
: nsIRevocationState
{
43 readonly attribute ACString issuer
;
44 readonly attribute ACString serial
;
48 * An interface representing the revocation state of a certificate by subject
49 * and pub key hash (the hash algorithm should be SHA-256). Both subject name
50 * and public key hash are base64-encoded.
52 [scriptable
, uuid(e78b51b4
-6fa4
-41e2
-92ce
-e9404f541e96
)]
53 interface nsISubjectAndPubKeyRevocationState
: nsIRevocationState
{
54 readonly attribute ACString subject
;
55 readonly attribute ACString pubKey
;
59 * An interface representing a set of certificates that are covered by a CRLite
60 * filter. The set is represented by a certificate transparency log ID and a
61 * pair of timestamps. The timestamps are such that the CRLite aggregator has
62 * seen every certificate from the specified log with an SCT between the two
64 * b64LogID is a base 64-encoded RFC 6962 LogID.
65 * minTimestamp is the smallest timestamp that the CRLite filter covers.
66 * maxTimestamp is the largest timestamp that the CRLite filter covers.
68 [scriptable
, uuid(416453f7
-29bd
-4820-a039
-9c2e055d3715
)]
69 interface nsICRLiteCoverage
: nsISupports
{
70 readonly attribute ACString b64LogID
;
71 readonly attribute
unsigned long long minTimestamp
;
72 readonly attribute
unsigned long long maxTimestamp
;
76 * An interface representing the id and timestamp fields from an RFC 6962
77 * SignedCertificateTimestamp struct.
78 * logID is the id field.
79 * timestamp is the timestamp field.
81 [uuid(9676cfc4
-6e84
-11ec
-a30d
-d3cd0af86e01
)]
82 interface nsICRLiteTimestamp
: nsISupports
{
83 readonly attribute Array
<octet
> logID
;
84 readonly attribute
unsigned long long timestamp
;
88 * An interface representing a certificate to add to storage. Consists of the
89 * base64-encoded DER bytes of the certificate (cert), the base64-encoded DER
90 * bytes of the subject distinguished name of the certificate (subject), and the
91 * trust of the certificate (one of the nsICertStorage.TRUST_* constants).
92 * (Note that this implementation does not validate that the given subject DN
93 * actually matches the subject DN of the certificate, nor that the given cert
94 * is a valid DER X.509 certificate.)
96 [scriptable
, uuid(27b66f5e
-0faf
-403b
-95b4
-bc11691ac50d
)]
97 interface nsICertInfo
: nsISupports
{
98 readonly attribute ACString cert
;
99 readonly attribute ACString subject
;
100 readonly attribute
short trust
;
103 [scriptable
, uuid(327100a7
-3401-45ef
-b160
-bf880f1016fd
)]
104 interface nsICertStorage
: nsISupports
{
105 const octet DATA_TYPE_REVOCATION
= 1;
106 const octet DATA_TYPE_CERTIFICATE
= 2;
107 const octet DATA_TYPE_CRLITE
= 3;
108 const octet DATA_TYPE_CRLITE_FILTER_FULL
= 4;
109 const octet DATA_TYPE_CRLITE_FILTER_INCREMENTAL
= 5;
112 * Asynchronously check if the backing storage has stored data of the given
113 * type in the past. This is useful if the backing storage may have had to
114 * have been deleted and recreated (as in bug 1546361 when we discovered that
115 * moving from a 32-bit binary to a 64-bit binary caused the DB to become
116 * unreadable, thus necessitating its deletion and recreation).
119 void hasPriorData
(in octet type
, in nsICertStorageCallback
callback);
121 const short STATE_UNSET
= 0;
122 const short STATE_ENFORCE
= 1;
123 const short STATE_NOT_ENROLLED
= 2;
124 const short STATE_NOT_COVERED
= 3;
125 const short STATE_NO_FILTER
= 4;
128 * Asynchronously set the revocation states of a set of certificates.
129 * The given callback is called with the result of the operation when it
131 * Must only be called from the main thread.
134 void setRevocations
(in Array
<nsIRevocationState
> revocations
,
135 in nsICertStorageCallback
callback);
138 * Get the revocation state of a certificate. STATE_UNSET indicates the
139 * certificate is not revoked. STATE_ENFORCE indicates the certificate is
141 * issuer - issuer name, DER encoded
142 * serial - serial number, DER encoded
143 * subject - subject name, DER encoded
144 * pubkey - public key, DER encoded
145 * In gecko, must not be called from the main thread. See bug 1541212.
146 * xpcshell tests may call this from the main thread.
149 short getRevocationState
(in Array
<octet
> issuer
,
150 in Array
<octet
> serial
,
151 in Array
<octet
> subject
,
152 in Array
<octet
> pubkey
);
155 * Given the contents of a new CRLite filter, a list containing
156 * `base64(sha256(subject DN || subject SPKI))` for each enrolled issuer, and
157 * the filter's timestamp coverage, replaces any existing filter with the new
158 * one. Also clears any previously-set incremental revocation updates
162 void setFullCRLiteFilter
(in Array
<octet
> filter
,
163 in Array
<ACString
> enrolledIssuers
,
164 in Array
<nsICRLiteCoverage
> coverage
,
165 in nsICertStorageCallback
callback);
168 * Given the DER-encoded issuer distinguished name, DER-encoded issuer subject public key info,
169 * the bytes of the value of the serial number (so, not including the DER tag and length) of a
170 * certificate, and the timestamps from that certificate's embedded SCTs, returns the result of
171 * looking up the corresponding entry in the currently-saved CRLite filter (if any).
173 * - STATE_ENFORCE if the lookup indicates the certificate is revoked via CRLite,
174 * - STATE_UNSET if the lookup indicates the certificate is not revoked via CRLite,
175 * - STATE_NOT_ENROLLED if the issuer is not enrolled in CRLite, or
176 * - STATE_NOT_COVERED if the issuer is enrolled but the provided timestamps indicate
177 * that the serial number is not covered by the current CRLite filter.
178 * - STATE_NO_FILTER if there is no (usable) CRLite filter.
179 * No lookup is performed in the STATE_NOT_ENROLLED and STATE_NOT_COVERED cases.
182 short getCRLiteRevocationState
(in Array
<octet
> issuer
,
183 in Array
<octet
> issuerSPKI
,
184 in Array
<octet
> serialNumber
,
185 in Array
<nsICRLiteTimestamp
> timestamps
);
188 * Given the contents of a CRLite incremental revocation update ("stash"), adds the revocation
189 * information to the current set of stashed revocations. The basic unit of the stash file is an
190 * issuer subject public key info hash (sha-256) followed by a number of serial numbers
191 * corresponding to revoked certificates issued by that issuer. More specifically, each unit
193 * 4 bytes little-endian: the number of serial numbers following the issuer spki hash
194 * 1 byte: the length of the issuer spki hash
195 * issuer spki hash length bytes: the issuer spki hash
196 * as many times as the indicated serial numbers:
197 * 1 byte: the length of the serial number
198 * serial number length bytes: the serial number
199 * The stash file consists of any number of these units concatenated together.
202 void addCRLiteStash
(in Array
<octet
> stash
, in nsICertStorageCallback
callback);
205 * Given a DER-encoded issuer subject public key info and the bytes of the value of the serial
206 * number (so, not including the DER tag and length), determines if the certificate identified by
207 * this issuer SPKI and serial number is revoked according to the current set of stashed CRLite
208 * revocation information.
211 bool isCertRevokedByStash
(in Array
<octet
> issuerSPKI
, in Array
<octet
> serialNumber
);
214 * Trust flags to use when adding a adding a certificate.
215 * TRUST_INHERIT indicates a certificate inherits trust from another
217 * TRUST_ANCHOR indicates the certificate is a root of trust.
219 const short TRUST_INHERIT
= 0;
220 const short TRUST_ANCHOR
= 1;
223 * Asynchronously add a list of certificates to the backing storage.
224 * See the documentation for nsICertInfo.
225 * The given callback is called with the result of the operation when it
227 * Must only be called from the main thread.
230 void addCerts
(in Array
<nsICertInfo
> certs
, in nsICertStorageCallback
callback);
233 * Asynchronously remove the certificates with the given sha-256 hashes from
234 * the backing storage.
235 * hashes is an array of base64-encoded bytes of the sha-256 hashes of each
236 * certificate's bytes (DER-encoded).
237 * The given callback is called with the result of the operation when it
239 * Must only be called from the main thread.
242 void removeCertsByHashes
(in Array
<ACString
> hashes
,
243 in nsICertStorageCallback
callback);
246 * Find all certificates in the backing storage with the given subject
247 * distinguished name.
248 * subject is the DER-encoded bytes of the subject distinguished name.
249 * Returns an array of arrays of bytes, where each inner array corresponds to
250 * the DER-encoded bytes of a certificate that has the given subject (although
251 * as these certificates were presumably added via addCertBySubject, this
252 * aspect is never actually valided by nsICertStorage).
253 * Must not be called from the main thread. See bug 1541212.
256 Array
<Array
<octet
> > findCertsBySubject
(in Array
<octet
> subject
);
259 * Get the count of remaining async operations. Called to ensure we don't skip
260 * or interrupt any operations during fast shutdown.
261 * Must only be called from the main thread.
264 int32_t GetRemainingOperationCount
();