security/manager/ssl/nsICertStorage.idl

   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/. */
   5
   6 #include "nsISupports.idl"
   7 #include "nsIVariant.idl"
   8
   9 /**
  10  * Callback type used to notify callers that an operation performed by
  11  * nsICertStorage has completed. Indicates the result of the requested
  12  * operation, as well as any data returned by the operation.
  13  */
  14 [scriptable, function, uuid(3f8fe26a-a436-4ad4-9c1c-a53c60973c31)]
  15 interface nsICertStorageCallback : nsISupports {
  16   [must_use]
  17   void done(in nsresult rv, in nsIVariant result);
  18 };
  19
  20 /**
  21  * A base interface for representing the revocation state of a certificate.
  22  * Implementing this interface by itself is insufficient; your type must
  23  * implement an inheriting interface that specifies the certificate by issuer
  24  * and serial number or by subject and public key hash.
  25  * Set state to nsICertStorage.STATE_UNSET to mark the certificate as not revoked.
  26  * Set state to nsICertStorage.STATE_ENFORCE to mark the certificate as revoked.
  27  */
  28 [scriptable, uuid(96db6fd7-6b64-4a5a-955d-310bd9ca4234)]
  29 interface nsIRevocationState : nsISupports {
  30   readonly attribute short state;
  31 };
  32
  33 /**
  34  * An interface representing the revocation state of a certificate by issuer
  35  * and serial number. Both issuer name and serial number are base64-encoded.
  36  */
  37 [scriptable, uuid(23ce3546-f1b9-46f6-8de3-77704da5702f)]
  38 interface nsIIssuerAndSerialRevocationState : nsIRevocationState {
  39     readonly attribute ACString issuer;
  40     readonly attribute ACString serial;
  41 };
  42
  43 /**
  44  * An interface representing the revocation state of a certificate by subject
  45  * and pub key hash (the hash algorithm should be SHA-256). Both subject name
  46  * and public key hash are base64-encoded.
  47  */
  48 [scriptable, uuid(e78b51b4-6fa4-41e2-92ce-e9404f541e96)]
  49 interface nsISubjectAndPubKeyRevocationState : nsIRevocationState {
  50     readonly attribute ACString subject;
  51     readonly attribute ACString pubKey;
  52 };
  53
  54 /**
  55  * An interface representing a set of certificates that are covered by a CRLite
  56  * filter. The set is represented by a certificate transparency log ID and a
  57  * pair of timestamps. The timestamps are such that the CRLite aggregator has
  58  * seen every certificate from the specified log with an SCT between the two
  59  * timestamps.
  60  * b64LogID is a base 64-encoded RFC 6962 LogID.
  61  * minTimestamp is the smallest timestamp that the CRLite filter covers.
  62  * maxTimestamp is the largest timestamp that the CRLite filter covers.
  63  */
  64 [scriptable, uuid(416453f7-29bd-4820-a039-9c2e055d3715)]
  65 interface nsICRLiteCoverage : nsISupports {
  66     readonly attribute ACString b64LogID;
  67     readonly attribute unsigned long long minTimestamp;
  68     readonly attribute unsigned long long maxTimestamp;
  69 };
  70
  71 /**
  72  * An interface representing the id and timestamp fields from an RFC 6962
  73  * SignedCertificateTimestamp struct.
  74  * logID is the id field.
  75  * timestamp is the timestamp field.
  76  */
  77 [uuid(9676cfc4-6e84-11ec-a30d-d3cd0af86e01)]
  78 interface nsICRLiteTimestamp: nsISupports {
  79     readonly attribute Array<octet> logID;
  80     readonly attribute unsigned long long timestamp;
  81 };
  82
  83 /**
  84  * An interface representing a certificate to add to storage. Consists of the
  85  * base64-encoded DER bytes of the certificate (cert), the base64-encoded DER
  86  * bytes of the subject distinguished name of the certificate (subject), and the
  87  * trust of the certificate (one of the nsICertStorage.TRUST_* constants).
  88  * (Note that this implementation does not validate that the given subject DN
  89  * actually matches the subject DN of the certificate, nor that the given cert
  90  * is a valid DER X.509 certificate.)
  91  */
  92 [scriptable, uuid(27b66f5e-0faf-403b-95b4-bc11691ac50d)]
  93 interface nsICertInfo : nsISupports {
  94   readonly attribute ACString cert;
  95   readonly attribute ACString subject;
  96   readonly attribute short trust;
  97 };
  98
  99 [scriptable, uuid(327100a7-3401-45ef-b160-bf880f1016fd)]
 100 interface nsICertStorage : nsISupports {
 101   const octet DATA_TYPE_REVOCATION = 1;
 102   const octet DATA_TYPE_CERTIFICATE = 2;
 103   const octet DATA_TYPE_CRLITE = 3;
 104   const octet DATA_TYPE_CRLITE_FILTER_FULL = 4;
 105   const octet DATA_TYPE_CRLITE_FILTER_INCREMENTAL = 5;
 106
 107   /**
 108    * Asynchronously check if the backing storage has stored data of the given
 109    * type in the past. This is useful if the backing storage may have had to
 110    * have been deleted and recreated (as in bug 1546361 when we discovered that
 111    * moving from a 32-bit binary to a 64-bit binary caused the DB to become
 112    * unreadable, thus necessitating its deletion and recreation).
 113    */
 114   [must_use]
 115   void hasPriorData(in octet type, in nsICertStorageCallback callback);
 116
 117   const short STATE_UNSET = 0;
 118   const short STATE_ENFORCE = 1;
 119   const short STATE_NOT_ENROLLED = 2;
 120   const short STATE_NOT_COVERED = 3;
 121   const short STATE_NO_FILTER = 4;
 122
 123   /**
 124    * Asynchronously set the revocation states of a set of certificates.
 125    * The given callback is called with the result of the operation when it
 126    * completes.
 127    * Must only be called from the main thread.
 128    */
 129   [must_use]
 130   void setRevocations(in Array<nsIRevocationState> revocations,
 131                       in nsICertStorageCallback callback);
 132
 133   /**
 134    * Get the revocation state of a certificate. STATE_UNSET indicates the
 135    * certificate is not revoked. STATE_ENFORCE indicates the certificate is
 136    * revoked.
 137    * issuer - issuer name, DER encoded
 138    * serial - serial number, DER encoded
 139    * subject - subject name, DER encoded
 140    * pubkey - public key, DER encoded
 141    * In gecko, must not be called from the main thread. See bug 1541212.
 142    * xpcshell tests may call this from the main thread.
 143    */
 144   [must_use]
 145   short getRevocationState(in Array<octet> issuer,
 146                            in Array<octet> serial,
 147                            in Array<octet> subject,
 148                            in Array<octet> pubkey);
 149
 150   /**
 151    * Given the contents of a new CRLite filter, a list containing
 152    * `base64(sha256(subject DN || subject SPKI))` for each enrolled issuer, and
 153    * the filter's timestamp coverage, replaces any existing filter with the new
 154    * one. Also clears any previously-set incremental revocation updates
 155    * ("stashes" or "deltas").
 156    */
 157   [must_use]
 158   void setFullCRLiteFilter(in Array<octet> filter,
 159                            in Array<ACString> enrolledIssuers,
 160                            in Array<nsICRLiteCoverage> coverage,
 161                            in nsICertStorageCallback callback);
 162
 163   /**
 164    * Given the DER-encoded issuer distinguished name, DER-encoded issuer subject public key info,
 165    * the bytes of the value of the serial number (so, not including the DER tag and length) of a
 166    * certificate, and the timestamps from that certificate's embedded SCTs, returns the result of
 167    * looking up the corresponding entry in the currently-saved CRLite filter (if any).
 168    * Returns
 169    *    - STATE_ENFORCE if the lookup indicates the certificate is revoked via CRLite,
 170    *    - STATE_UNSET if the lookup indicates the certificate is not revoked via CRLite,
 171    *    - STATE_NOT_ENROLLED if the issuer is not enrolled in CRLite, or
 172    *    - STATE_NOT_COVERED if the issuer is enrolled but the provided timestamps indicate
 173    *      that the serial number is not covered by the current CRLite filter.
 174    *    - STATE_NO_FILTER if there is no (usable) CRLite filter.
 175    * No lookup is performed in the STATE_NOT_ENROLLED and STATE_NOT_COVERED cases.
 176    */
 177   [must_use, noscript]
 178   short getCRLiteRevocationState(in Array<octet> issuer,
 179                                  in Array<octet> issuerSPKI,
 180                                  in Array<octet> serialNumber,
 181                                  in Array<nsICRLiteTimestamp> timestamps);
 182
 183   /**
 184    * Given the contents of a CRLite incremental revocation update ("stash"), adds the revocation
 185    * information to the current set of stashed revocations. The basic unit of the stash file is an
 186    * issuer subject public key info hash (sha-256) followed by a number of serial numbers
 187    * corresponding to revoked certificates issued by that issuer. More specifically, each unit
 188    * consists of:
 189    *   4 bytes little-endian: the number of serial numbers following the issuer spki hash
 190    *   1 byte: the length of the issuer spki hash
 191    *   issuer spki hash length bytes: the issuer spki hash
 192    *   as many times as the indicated serial numbers:
 193    *     1 byte: the length of the serial number
 194    *     serial number length bytes: the serial number
 195    * The stash file consists of any number of these units concatenated together.
 196    */
 197   [must_use]
 198   void addCRLiteStash(in Array<octet> stash, in nsICertStorageCallback callback);
 199
 200   /**
 201    * Add a new CRLite filter for consideration in revocation checks. This
 202    * filter is treated as a delta update to the current full filter. Calling
 203    * this function will not remove the existing full filter, stashes, or delta
 204    * updates. A copy of the new filter will be written to the user's
 205    * security_state directory with the given filename.
 206    */
 207   [must_use]
 208   void addCRLiteDelta(in Array<octet> delta, in ACString filename, in nsICertStorageCallback callback);
 209
 210   /**
 211    * Given a DER-encoded issuer subject public key info and the bytes of the value of the serial
 212    * number (so, not including the DER tag and length), determines if the certificate identified by
 213    * this issuer SPKI and serial number is revoked according to the current set of stashed CRLite
 214    * revocation information.
 215    */
 216   [must_use, noscript]
 217   boolean isCertRevokedByStash(in Array<octet> issuerSPKI, in Array<octet> serialNumber);
 218
 219   /**
 220    * Trust flags to use when adding a adding a certificate.
 221    * TRUST_INHERIT indicates a certificate inherits trust from another
 222    * certificate.
 223    * TRUST_ANCHOR indicates the certificate is a root of trust.
 224    */
 225   const short TRUST_INHERIT = 0;
 226   const short TRUST_ANCHOR = 1;
 227
 228   /**
 229    * Asynchronously add a list of certificates to the backing storage.
 230    * See the documentation for nsICertInfo.
 231    * The given callback is called with the result of the operation when it
 232    * completes.
 233    * Must only be called from the main thread.
 234    */
 235   [must_use]
 236   void addCerts(in Array<nsICertInfo> certs, in nsICertStorageCallback callback);
 237
 238   /**
 239    * Asynchronously remove the certificates with the given sha-256 hashes from
 240    * the backing storage.
 241    * hashes is an array of base64-encoded bytes of the sha-256 hashes of each
 242    * certificate's bytes (DER-encoded).
 243    * The given callback is called with the result of the operation when it
 244    * completes.
 245    * Must only be called from the main thread.
 246    */
 247   [must_use]
 248   void removeCertsByHashes(in Array<ACString> hashes,
 249                            in nsICertStorageCallback callback);
 250
 251   /**
 252    * Find all certificates in the backing storage with the given subject
 253    * distinguished name.
 254    * subject is the DER-encoded bytes of the subject distinguished name.
 255    * Returns an array of arrays of bytes, where each inner array corresponds to
 256    * the DER-encoded bytes of a certificate that has the given subject (although
 257    * as these certificates were presumably added via addCertBySubject, this
 258    * aspect is never actually valided by nsICertStorage).
 259    * Must not be called from the main thread. See bug 1541212.
 260    */
 261   [must_use]
 262   Array<Array<octet> > findCertsBySubject(in Array<octet> subject);
 263
 264   /**
 265    * Get the count of remaining async operations. Called to ensure we don't skip
 266    * or interrupt any operations during fast shutdown.
 267    * Must only be called from the main thread.
 268    */
 269   [must_use]
 270   int32_t GetRemainingOperationCount();
 271 };