nsICertStorage.idl (10266B)
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 the id and timestamp fields from an RFC 6962 56 * SignedCertificateTimestamp struct. 57 * logID is the id field. 58 * timestamp is the timestamp field. 59 */ 60 [uuid(9676cfc4-6e84-11ec-a30d-d3cd0af86e01)] 61 interface nsICRLiteTimestamp: nsISupports { 62 readonly attribute Array<octet> logID; 63 readonly attribute unsigned long long timestamp; 64 }; 65 66 /** 67 * An interface representing a certificate to add to storage. Consists of the 68 * base64-encoded DER bytes of the certificate (cert), the base64-encoded DER 69 * bytes of the subject distinguished name of the certificate (subject), and the 70 * trust of the certificate (one of the nsICertStorage.TRUST_* constants). 71 * (Note that this implementation does not validate that the given subject DN 72 * actually matches the subject DN of the certificate, nor that the given cert 73 * is a valid DER X.509 certificate.) 74 */ 75 [scriptable, uuid(27b66f5e-0faf-403b-95b4-bc11691ac50d)] 76 interface nsICertInfo : nsISupports { 77 readonly attribute ACString cert; 78 readonly attribute ACString subject; 79 readonly attribute short trust; 80 }; 81 82 [scriptable, uuid(327100a7-3401-45ef-b160-bf880f1016fd)] 83 interface nsICertStorage : nsISupports { 84 const octet DATA_TYPE_REVOCATION = 1; 85 const octet DATA_TYPE_CERTIFICATE = 2; 86 const octet DATA_TYPE_CRLITE = 3; 87 const octet DATA_TYPE_CRLITE_FILTER_FULL = 4; 88 const octet DATA_TYPE_CRLITE_FILTER_INCREMENTAL = 5; 89 90 /** 91 * Asynchronously check if the backing storage has stored data of the given 92 * type in the past. This is useful if the backing storage may have had to 93 * have been deleted and recreated (as in bug 1546361 when we discovered that 94 * moving from a 32-bit binary to a 64-bit binary caused the DB to become 95 * unreadable, thus necessitating its deletion and recreation). 96 */ 97 [must_use] 98 void hasPriorData(in octet type, in nsICertStorageCallback callback); 99 100 const short STATE_UNSET = 0; 101 const short STATE_ENFORCE = 1; 102 const short STATE_NOT_ENROLLED = 2; 103 const short STATE_NOT_COVERED = 3; 104 const short STATE_NO_FILTER = 4; 105 106 /** 107 * Asynchronously set the revocation states of a set of certificates. 108 * The given callback is called with the result of the operation when it 109 * completes. 110 * Must only be called from the main thread. 111 */ 112 [must_use] 113 void setRevocations(in Array<nsIRevocationState> revocations, 114 in nsICertStorageCallback callback); 115 116 /** 117 * Get the revocation state of a certificate. STATE_UNSET indicates the 118 * certificate is not revoked. STATE_ENFORCE indicates the certificate is 119 * revoked. 120 * issuer - issuer name, DER encoded 121 * serial - serial number, DER encoded 122 * subject - subject name, DER encoded 123 * pubkey - public key, DER encoded 124 * In gecko, must not be called from the main thread. See bug 1541212. 125 * xpcshell tests may call this from the main thread. 126 */ 127 [must_use] 128 short getRevocationState(in Array<octet> issuer, 129 in Array<octet> serial, 130 in Array<octet> subject, 131 in Array<octet> pubkey); 132 133 /** 134 * Given the contents of a new CRLite filter, replaces any existing filter 135 * with the new one. Also clears any previously-set incremental revocation 136 * updates ("deltas"). 137 */ 138 [must_use] 139 void setFullCRLiteFilter(in Array<octet> filter, 140 in nsICertStorageCallback callback); 141 142 /** 143 * Given the DER-encoded issuer subject public key info, the bytes of the 144 * value of the serial number (so, not including the DER tag and length) of a 145 * certificate, and the timestamps from that certificate's embedded SCTs, 146 * returns the result of looking up the corresponding entry in the 147 * currently-saved CRLite filter (if any). 148 * Returns 149 * - STATE_ENFORCE if the lookup indicates the certificate is revoked via CRLite, 150 * - STATE_UNSET if the lookup indicates the certificate is not revoked via CRLite, 151 * - STATE_NOT_ENROLLED if the issuer is not enrolled in CRLite, or 152 * - STATE_NOT_COVERED if the issuer is enrolled but the provided timestamps indicate 153 * that the serial number is not covered by the current CRLite filter. 154 * - STATE_NO_FILTER if there is no (usable) CRLite filter. 155 * No lookup is performed in the STATE_NOT_ENROLLED and STATE_NOT_COVERED cases. 156 */ 157 [must_use, noscript] 158 short getCRLiteRevocationState(in Array<octet> issuerSPKI, 159 in Array<octet> serialNumber, 160 in Array<nsICRLiteTimestamp> timestamps); 161 162 /** 163 * Add a new CRLite filter for consideration in revocation checks. This 164 * filter is treated as a delta update to the current full filter. Calling 165 * this function will not remove the existing full filter, stashes, or delta 166 * updates. A copy of the new filter will be written to the user's 167 * security_state directory with the given filename. 168 */ 169 [must_use] 170 void addCRLiteDelta(in Array<octet> delta, in ACString filename, in nsICertStorageCallback callback); 171 172 /** 173 * Mark CRLite filters as fresh. For use in tests only. 174 */ 175 [must_use] 176 void testNoteCRLiteUpdateTime(in nsICertStorageCallback callback); 177 178 /** 179 * Trust flags to use when adding a adding a certificate. 180 * TRUST_INHERIT indicates a certificate inherits trust from another 181 * certificate. 182 * TRUST_ANCHOR indicates the certificate is a root of trust. 183 */ 184 const short TRUST_INHERIT = 0; 185 const short TRUST_ANCHOR = 1; 186 187 /** 188 * Asynchronously add a list of certificates to the backing storage. 189 * See the documentation for nsICertInfo. 190 * The given callback is called with the result of the operation when it 191 * completes. 192 * Must only be called from the main thread. 193 */ 194 [must_use] 195 void addCerts(in Array<nsICertInfo> certs, in nsICertStorageCallback callback); 196 197 /** 198 * Synchronously add a certificate to the backing storage. 199 * See the documentation for nsICertInfo. 200 * This is a helper which should only be called from tests. 201 */ 202 void TestHelperAddCert(in ACString cert, in ACString subject, in short trust); 203 204 /** 205 * Asynchronously remove the certificates with the given sha-256 hashes from 206 * the backing storage. 207 * hashes is an array of base64-encoded bytes of the sha-256 hashes of each 208 * certificate's bytes (DER-encoded). 209 * The given callback is called with the result of the operation when it 210 * completes. 211 * Must only be called from the main thread. 212 */ 213 [must_use] 214 void removeCertsByHashes(in Array<ACString> hashes, 215 in nsICertStorageCallback callback); 216 217 /** 218 * Find all certificates in the backing storage with the given subject 219 * distinguished name. 220 * subject is the DER-encoded bytes of the subject distinguished name. 221 * Returns an array of arrays of bytes, where each inner array corresponds to 222 * the DER-encoded bytes of a certificate that has the given subject (although 223 * as these certificates were presumably added via addCertBySubject, this 224 * aspect is never actually valided by nsICertStorage). 225 * Must not be called from the main thread. See bug 1541212. 226 */ 227 [must_use] 228 Array<Array<octet> > findCertsBySubject(in Array<octet> subject); 229 230 /** 231 * Check for presence of all certificates in backing storage identified 232 * by the list of hashes. Returns true or false accordingly. 233 * Must not be called from the main thread. See bug 1541212. 234 */ 235 [must_use] 236 boolean hasAllCertsByHash(in Array<Array<octet> > hashes); 237 238 /** 239 * Finds a certificate in backing storage, identified by SHA256 of the 240 * DER-encoded bytes of the certificate. Returns an array of bytes 241 * representing the DER-encoded bytes of the certificate. 242 * Must not be called from the main thread. See bug 1541212. 243 */ 244 [must_use] 245 Array<octet> findCertByHash(in Array<octet> cert_hash); 246 247 /** 248 * Get the count of remaining async operations. Called to ensure we don't skip 249 * or interrupt any operations during fast shutdown. 250 * Must only be called from the main thread. 251 */ 252 [must_use] 253 int32_t GetRemainingOperationCount(); 254 };