nsIX509CertDB.idl (16748B)
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/. */ 6 7 #include "nsISupports.idl" 8 9 interface nsIArray; 10 interface nsIX509Cert; 11 interface nsIFile; 12 interface nsIInterfaceRequestor; 13 interface nsIZipReader; 14 interface nsIInputStream; 15 16 %{C++ 17 #define NS_X509CERTDB_CONTRACTID "@mozilla.org/security/x509certdb;1" 18 %} 19 20 typedef uint32_t AppTrustedRoot; 21 22 [scriptable, builtinclass, uuid(e5795418-86e0-4c0b-9b98-ac7eee0c2af7)] 23 interface nsIAppSignatureInfo : nsISupports { 24 // Supported signature algorithms. 25 cenum SignatureAlgorithm : 32 { 26 PKCS7_WITH_SHA1, 27 PKCS7_WITH_SHA256, 28 COSE_WITH_SHA256, 29 }; 30 31 // The certificate that created the signature. 32 readonly attribute nsIX509Cert signerCert; 33 readonly attribute nsIAppSignatureInfo_SignatureAlgorithm signatureAlgorithm; 34 }; 35 36 [scriptable, function, uuid(fc2b60e5-9a07-47c2-a2cd-b83b68a660ac)] 37 interface nsIOpenSignedAppFileCallback : nsISupports 38 { 39 void openSignedAppFileFinished(in nsresult rv, 40 in nsIZipReader aZipReader, 41 in Array<nsIAppSignatureInfo> aSignatureInfos); 42 }; 43 44 /** 45 * Return type to be used in asyncVerifyPKCS7Object for PDF Verification. 46 * Consists of 3 elements: 47 * signatureResult describes the result of verifying the hash of data against the signature 48 * stored in pkcs7 49 * certificateResult describes the result of certificate verification 50 * If the signature verification has failed, certificate verification is not run. 51 * signerCertificate returns the signerCertificate from the pkcs7 message 52 * signerCertificate is null if the signature verification has failed (not equal to NS_OK). 53 */ 54 [scriptable, uuid(f2d9f5e4-1234-4d5a-b789-abcdef012345)] 55 interface nsIPDFVerificationResult : nsISupports { 56 readonly attribute nsresult signatureResult; 57 readonly attribute nsresult certificateResult; 58 readonly attribute nsIX509Cert signerCertificate; 59 }; 60 61 /** 62 * Callback type for use with asyncVerifyCertAtTime. 63 * If aPRErrorCode is PRErrorCodeSuccess (i.e. 0), aVerifiedChain represents the 64 * verified certificate chain determined by asyncVerifyCertAtTime. aHasEVPolicy 65 * represents whether or not the end-entity certificate verified as EV. 66 * If aPRErrorCode is non-zero, it represents the error encountered during 67 * verification. aVerifiedChain is null in that case and aHasEVPolicy has no 68 * meaning. 69 */ 70 [scriptable, function, uuid(49e16fc8-efac-4f57-8361-956ef6b960a4)] 71 interface nsICertVerificationCallback : nsISupports { 72 void verifyCertFinished(in int32_t aPRErrorCode, 73 in Array<nsIX509Cert> aVerifiedChain, 74 in boolean aHasEVPolicy); 75 }; 76 77 /** 78 * This represents a service to access and manipulate 79 * X.509 certificates stored in a database. 80 */ 81 [scriptable, uuid(5c16cd9b-5a73-47f1-ab0f-11ede7495cce)] 82 interface nsIX509CertDB : nsISupports { 83 84 /** 85 * Constants that define which usages a certificate 86 * is trusted for. 87 */ 88 const unsigned long UNTRUSTED = 0; 89 const unsigned long TRUSTED_SSL = 1 << 0; 90 const unsigned long TRUSTED_EMAIL = 1 << 1; 91 92 /** 93 * Will find a certificate based on its dbkey 94 * retrieved by getting the dbKey attribute of 95 * the certificate. 96 * 97 * @param aDBkey Database internal key, as obtained using 98 * attribute dbkey in nsIX509Cert. 99 */ 100 [must_use] 101 nsIX509Cert findCertByDBKey(in ACString aDBkey); 102 103 /** 104 * Use this to import a stream sent down as a mime type into 105 * the certificate database on the default token. 106 * The stream may consist of one or more certificates. 107 * 108 * @param data The raw data to be imported 109 * @param length The length of the data to be imported 110 * @param type The type of the certificate, see constants in nsIX509Cert 111 * @param ctx A UI context. 112 */ 113 void importCertificates([array, size_is(length)] in octet data, 114 in unsigned long length, 115 in unsigned long type, 116 in nsIInterfaceRequestor ctx); 117 118 /** 119 * Import another person's email certificate into the database. 120 * 121 * @param data The raw data to be imported 122 * @param length The length of the data to be imported 123 * @param ctx A UI context. 124 */ 125 void importEmailCertificate([array, size_is(length)] in octet data, 126 in unsigned long length, 127 in nsIInterfaceRequestor ctx); 128 129 /** 130 * Import a personal certificate into the database, assuming 131 * the database already contains the private key for this certificate. 132 * 133 * @param data The raw data to be imported 134 * @param length The length of the data to be imported 135 * @param ctx A UI context. 136 */ 137 void importUserCertificate([array, size_is(length)] in octet data, 138 in unsigned long length, 139 in nsIInterfaceRequestor ctx); 140 141 /** 142 * Delete a certificate stored in the database. 143 * 144 * @param aCert Delete this certificate. 145 */ 146 void deleteCertificate(in nsIX509Cert aCert); 147 148 /** 149 * Modify the trust that is stored and associated to a certificate within 150 * a database. Separate trust is stored for 151 * One call manipulates the trust for one trust type only. 152 * See the trust type constants defined within this interface. 153 * 154 * @param cert Change the stored trust of this certificate. 155 * @param type The type of the certificate. See nsIX509Cert. 156 * @param trust A bitmask. The new trust for the possible usages. 157 * See the trust constants defined within this interface. 158 */ 159 [must_use] 160 void setCertTrust(in nsIX509Cert cert, 161 in unsigned long type, 162 in unsigned long trust); 163 164 /** 165 * @param cert The certificate for which to modify trust. 166 * @param trustString decoded by CERT_DecodeTrustString. 3 comma separated 167 * characters, indicating SSL, Email, and Object signing 168 * trust. The object signing trust flags are effectively 169 * ignored by gecko, but they still must be specified (at 170 * least by a final trailing comma) because this argument 171 * is passed to CERT_DecodeTrustString. 172 */ 173 [must_use] 174 void setCertTrustFromString(in nsIX509Cert cert, in ACString trustString); 175 176 /** 177 * Query whether a certificate is trusted for a particular use. 178 * 179 * @param cert Obtain the stored trust of this certificate. 180 * @param certType The type of the certificate. See nsIX509Cert. 181 * @param trustType A single bit from the usages constants defined 182 * within this interface. 183 * 184 * @return Returns true if the certificate is trusted for the given use. 185 */ 186 [must_use] 187 boolean isCertTrusted(in nsIX509Cert cert, 188 in unsigned long certType, 189 in unsigned long trustType); 190 191 /** 192 * Import certificate(s) from file 193 * 194 * @param aFile Identifies a file that contains the certificate 195 * to be imported. 196 * @param aType Describes the type of certificate that is going to 197 * be imported. See type constants in nsIX509Cert. 198 */ 199 [must_use] 200 void importCertsFromFile(in nsIFile aFile, 201 in unsigned long aType); 202 203 const uint32_t Success = 0; 204 const uint32_t ERROR_UNKNOWN = 1; 205 const uint32_t ERROR_PKCS12_NOSMARTCARD_EXPORT = 2; 206 const uint32_t ERROR_PKCS12_RESTORE_FAILED = 3; 207 const uint32_t ERROR_PKCS12_BACKUP_FAILED = 4; 208 const uint32_t ERROR_PKCS12_CERT_COLLISION = 5; 209 const uint32_t ERROR_BAD_PASSWORD = 6; 210 const uint32_t ERROR_DECODE_ERROR = 7; 211 const uint32_t ERROR_PKCS12_DUPLICATE_DATA = 8; 212 213 /** 214 * Import a PKCS#12 file containing cert(s) and key(s) into the database. 215 * 216 * @param aFile Identifies a file that contains the data to be imported. 217 * @param password The password used to protect the file. 218 * @return Success or the specific error code on failure. The return 219 * values are defined in this file. 220 */ 221 [must_use] 222 uint32_t importPKCS12File(in nsIFile aFile, in AString aPassword); 223 224 /** 225 * Export a set of certs and keys from the database to a PKCS#12 file. 226 * 227 * @param aFile Identifies a file that will be filled with the data to be 228 * exported. 229 * @param count The number of certificates to be exported. 230 * @param aCerts The array of all certificates to be exported. 231 * @param password The password used to protect the file. 232 * @return Success or the specific error code on failure 233 */ 234 [must_use] 235 uint32_t exportPKCS12File(in nsIFile aFile, 236 in Array<nsIX509Cert> aCerts, 237 in AString aPassword); 238 239 /* 240 * Decode a raw data presentation and instantiate an object in memory. 241 * 242 * @param base64 The raw representation of a certificate, 243 * encoded as Base 64. 244 * @return The new certificate object. 245 */ 246 [must_use] 247 nsIX509Cert constructX509FromBase64(in ACString base64); 248 249 /* 250 * Decode a raw data presentation and instantiate an object in memory. 251 * 252 * @param certDER The raw representation of a certificate, 253 * encoded as raw DER. 254 * @return The new certificate object. 255 */ 256 [must_use] 257 nsIX509Cert constructX509(in Array<uint8_t> certDER); 258 259 /** 260 * Verifies the signature on the given JAR file to verify that it has a 261 * valid signature. To be considered valid, there must be exactly one 262 * signature on the JAR file and that signature must have signed every 263 * entry. Further, the signature must come from a certificate that 264 * is trusted for code signing. 265 * 266 * On success, NS_OK, a nsIZipReader, and the trusted certificate that 267 * signed the JAR are returned. 268 * 269 * On failure, an error code is returned. 270 * 271 * This method returns a nsIZipReader, instead of taking an nsIZipReader 272 * as input, to encourage users of the API to verify the signature as the 273 * first step in opening the JAR. 274 */ 275 // 1 used to be AppMarketplaceProdPublicRoot. 276 // 2 used to be AppMarketplaceProdReviewersRoot. 277 // 3 used to be AppMarketplaceDevPublicRoot. 278 // 4 used to be AppMarketplaceDevReviewersRoot. 279 // 5 used to be AppMarketplaceStageRoot. 280 const AppTrustedRoot AppXPCShellRoot = 6; 281 const AppTrustedRoot AddonsPublicRoot = 7; 282 const AppTrustedRoot AddonsStageRoot = 8; 283 [must_use] 284 void openSignedAppFileAsync(in AppTrustedRoot trustedRoot, 285 in nsIFile aJarFile, 286 in nsIOpenSignedAppFileCallback callback); 287 288 /* 289 * Add a cert to a cert DB from a binary string. 290 * 291 * @param certDER The raw DER encoding of a certificate. 292 * @param trust String describing the trust settings to assign the 293 * certificate. Decoded by CERT_DecodeTrustString. Consists of 3 294 * comma separated sets of characters, indicating SSL, Email, and 295 * Object signing trust. The object signing trust flags are 296 * effectively ignored by gecko, but they still must be specified 297 * (at least by a final trailing comma) because this argument is 298 * passed to CERT_DecodeTrustString. 299 * @return nsIX509Cert the resulting certificate 300 */ 301 [must_use] 302 nsIX509Cert addCert(in ACString certDER, in ACString trust); 303 304 // Flags for asyncVerifyCertAtTime (these must match the values in 305 // CertVerifier.cpp): 306 // Prevent network traffic. 307 const uint32_t FLAG_LOCAL_ONLY = 1 << 0; 308 // Do not fall back to DV verification after attempting EV validation. 309 const uint32_t FLAG_MUST_BE_EV = 1 << 1; 310 311 cenum VerifyUsage : 8 { 312 verifyUsageTLSServer = 1, 313 verifyUsageTLSServerCA = 2, 314 verifyUsageTLSClient = 3, 315 verifyUsageTLSClientCA = 4, 316 verifyUsageEmailSigner = 5, 317 verifyUsageEmailRecipient = 6, 318 verifyUsageEmailCA = 7, 319 }; 320 321 /* 322 * Asynchronously verify a certificate given a set of parameters. Calls the 323 * `verifyCertFinished` function on the provided `nsICertVerificationCallback` 324 * with the results of the verification operation. 325 * See the documentation for nsICertVerificationCallback. 326 * 327 * @param aCert the certificate to verify 328 * @param aUsage see VerifyUsage, the usage to verify for 329 * @param aFlags flags as described above 330 * @param aHostname the (optional) hostname to verify for 331 * @param aTime the time at which to verify, in seconds since the epoch 332 * @param aSctsFromTls an (optional) RFC6962 SignedCertificateTimestampList 333 * @param aCallback the nsICertVerificationCallback that will receive the 334 results of this verification 335 * @return a succeeding nsresult if the job was dispatched successfully 336 */ 337 [must_use] 338 void asyncVerifyCertAtTime(in nsIX509Cert aCert, 339 in nsIX509CertDB_VerifyUsage aUsage, 340 in uint32_t aFlags, 341 in ACString aHostname, 342 in uint64_t aTime, 343 in Array<uint8_t> aSctsFromTls, 344 in nsICertVerificationCallback aCallback); 345 346 // Clears the OCSP cache for the current certificate verification 347 // implementation. 348 [must_use] 349 void clearOCSPCache(); 350 351 /* 352 * Add a cert to a cert DB from a base64 encoded string. 353 * 354 * @param base64 The raw representation of a certificate, encoded as Base 64. 355 * @param trust String describing the trust settings to assign the 356 * certificate. Decoded by CERT_DecodeTrustString. Consists of 3 357 * comma separated sets of characters, indicating SSL, Email, and 358 * Object signing trust. The object signing trust flags are 359 * effectively ignored by gecko, but they still must be specified 360 * (at least by a final trailing comma) because this argument is 361 * passed to CERT_DecodeTrustString. 362 * @return nsIX509Cert the resulting certificate 363 */ 364 [must_use] 365 nsIX509Cert addCertFromBase64(in ACString base64, in ACString trust); 366 367 /* 368 * Get all the known certs in the database 369 */ 370 [must_use] 371 Array<nsIX509Cert> getCerts(); 372 373 /** 374 * Encode the list of certificates as a PKCS#7 SignedData structure. No data 375 * is actually signed - this is merely a way of exporting a collection of 376 * certificates. 377 */ 378 [must_use] 379 ACString asPKCS7Blob(in Array<nsIX509Cert> certList); 380 381 /** 382 * On Android, returns the client authentication certificate corresponding to 383 * the given alias that was previously returned by a call to 384 * `KeyChain.choosePrivateKeyAlias`. 385 */ 386 [must_use] 387 nsIX509Cert getAndroidCertificateFromAlias(in AString alias); 388 389 cenum QWACType : 8 { 390 OneQWAC, 391 TwoQWAC, 392 }; 393 394 /** 395 * For a QWAC type (1-QWAC or 2-QWAC), given a certificate, a hostname, and a 396 * list of other certificates that may be useful in path building, 397 * asynchronously determines whether or not the certificate in question is a 398 * QWAC ("qualified website authentication certificate") of that type as per 399 * ETSI TS 119 411-5 and related standards. 400 */ 401 [implicit_jscontext] 402 Promise asyncVerifyQWAC(in nsIX509CertDB_QWACType type, 403 in nsIX509Cert cert, 404 in ACString hostname, 405 in Array<nsIX509Cert> collectedCerts); 406 407 /** 408 * Verifies that the all the signatures in the PKCS7 CMS message are valid for the associated data. 409 * Additionally, for each of them, the function extracts the signing certificate and 410 * its certificate chain from the PKCS7 object, 411 * checks that the certificate was valid at the time of signing, 412 * and ensures the chain leads to a trusted root certificate. 413 * 414 * @param pkcs7 DER-encoded PKCS#7 binary data object. 415 * @param data The associated data that was signed. 416 * @param signatureType Currently we support only adbe.pkcs7.detached 417 * 418 * If resolved, AsyncVerifyPKCS7Object(pkcs7, data, signatureType) will return an Array of 419 * nsIPDFVerificationResult (See above for the interface details). 420 */ 421 422 /* ISO 32000-2 */ 423 cenum PDFSignatureAlgorithm : 8 { 424 ADBE_PKCS7_DETACHED, 425 ADBE_PKCS7_SHA1 426 }; 427 428 [implicit_jscontext] 429 Promise asyncVerifyPKCS7Object( 430 in Array<uint8_t> pkcs7, 431 in Array<Array<uint8_t> > data, 432 in nsIX509CertDB_PDFSignatureAlgorithm signatureType 433 ); 434 };