Copyright © 2019 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
This specification defines a JavaScript API for certificate related operations in web applications, such as retrieving a list of certificates, obtaining a public key and a private key associated with a certificate.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Web Certificate API Community Group as an Editor's Draft.
GitHub Issues are preferred for discussion of this specification.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. The group does not expect this document to become a W3C Recommendation. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 March 2019 W3C Process Document.
The goal of Web Certificate API is to define a javaScript API for certificate related operations in web applications, such as retrieving a list of certificates, obtaining a public key and a private key associated with a certificate.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The web API for certificate-based signing provides a certSign() method for the browser to accept the service provider's request and sign it with the user's private key.
The example below signs a messageBuffer with the user's private key and verifies the message signed with the public key passed along with the signed message.
var messageBuffer;
// Fill messageBuffer in type of ArrayBuffer with data you want to sign.
window.crypto.subtle.certSign(messageBuffer, { name: "RSASSA-PKCS1-v1_5", hash: { name: "SHA-256" }}, {"keyUsagses" : [ "nonRepudiation" ]})
.then(signedObject => {
// Do something with signedObject here
console.log(signedObject.certificate.publicKey);
console.log(buf2hex(signedObject.message));
return window.crypto.subtle.verify(
signedObject.certificate.publicKey.algorithm,
signedObject.certificate.publicKey,
signedObject.signedMessage,
signedObject.saltedMessage));
}).then(isValid => {
console.log(isValid);
});
})
.catch(error => {
// Handle exceptional case here
console.log(error.name + ":" + error.message);
});
partial interface SubtleCrypto {
Promise certSign(BufferSource dataToSign, AlgorithmIdentifier algorithm, CertificateOptions options);
};
The certSign () method performs the digital signature using the private key of the certificate selected by the user among the certificates satisfying the options given as parameters, and returns the result to Promise. The browser needs to get confirmation from the user before responding to the API. The set of signing behaviors is the same as the sign () method of the Web Crypto API.
It contains the message to use for signing. The browser can use this signature with additional information, depending on whether the option is salted or not.
It contains an information about the algorithm to use for signing.
It contains additional information such as limiting available certificates for signing and processing the message.
WebIDL[SecureContext, Exposed=Window] interfaceSignedObject{ readonly attribute Certificatecertificate; readonly attribute BufferSourcesaltedMessage; readonly attribute BufferSourcesignedMessage; };
SignedObject is the return value of the certSign() method. It contains information about the certificate that can verify the signed message and the private key used for signing.
It contains an information about the certificate that can verify the private key used for signing.
It contains the original message that was signed. The message passed as an argument to the certSign() method allows the browser to add salt information to the message, depending on the options passed with it, and the added message is then passed to saltedMessage. The browser can add to the message information, such as the host requesting the signature, to avoid man-in-the-middle attacks.
It contains a signed message. The signed message must be able to be validated through the Web Crypto API using the certificate information and the saltedMessage passed along.
WebIDL[SecureContext, Exposed=Window] interfaceCertificate{ readonly attribute DOMStringversion; readonly attribute DOMStringserialNumber; readonly attribute CertificatePrincipalsubject; readonly attribute CertificatePrincipalissuer; readonly attribute long longnotBefore; readonly attribute long longnotAfter; readonly attribute BufferSourcederEncodedBuffer; };
Certificate is an object that represents a certificate and contains the main information of the certificate and the full text of the certificate as defined in the X.509 standard.
It contains version information for certificates according to X.509.
It contains the serial number of the certificate issued by the issuer.
It contains the owner's information.
It contains information from the issuer.
It contains the first valid date of the certificate.
It contains the last valid date of the certificate.
It contains the full text of the X.509 certificate encoded in der.
WebIDL[SecureContext, Exposed=Window] interfaceCertificatePrincipal{ readonly attribute DOMStringdistinguishedNames; };
CertificatePrincipal contains information about the issuer and owner of a certificate in accordance with the X.509 standard.
It contains the distinguished name of the owner or issuer as defined in the X.509 standard in DN format.
typedef DOMString KeyUsage;
dictionary CertificateRequestOptions {
sequence keyUsages;
sequence issuer;
boolean useSalt;
};
CertificateRequestOptions contains the information needed to restrict the certificate and private key used for signing. The service provider can use this value to restrict the user to signing with a certificate that the service provider does not trust. CertificateRequestOptions is extensible for precise signatures.
The owner's public key contained in the certificate restricts the purpose for which it is used. It can consist of one or more of the following strings:
It is used on restrict issuers for signing.
The browser decides whether to sign by adding additional information to the message received through the certSign () method.
Certificates reject a promise object with the following DOMException in exceptional circumstances:
The web API for certificate-based signing handles the user's certificate and public / private key information, so the browser must pay special attention to security. This specification does not deal with spaces for storing user certificates and public / private keys, but browsers can exclude certificates and public / private keys that are not stored in secure storage. In addition, browsers can provide the ability for users to add, view, modify, or delete certificates and public / private keys used for web APIs for certificate-based signing, but are not covered in this specification.
The browser must obtain explicit confirmation from the user to retrieve the certificate or to sign the certificate. At this time, the user's confirmation cannot be used from different origins on the same web page. If the user does not agree, a NotAllowedError exception is raised.
Browsers can sign host messages and browser information in a signature message to prevent man-in-the-middle attacks or domain forgery. Through this, even if the attacker delivers the signed message, the service provider can check whether the message is directly received from the user by using the host information included in the message.