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.
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.
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.
[SecureContext, Exposed=Window]
interface SignedObject {
readonly attribute Certificate certificate;
readonly attribute BufferSource saltedMessage;
readonly attribute BufferSource signedMessage;
};
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.
[SecureContext, Exposed=Window]
interface Certificate {
readonly attribute DOMString version;
readonly attribute DOMString serialNumber;
readonly attribute CertificatePrincipal subject;
readonly attribute CertificatePrincipal issuer;
readonly attribute long long notBefore;
readonly attribute long long notAfter;
readonly attribute BufferSource derEncodedBuffer;
};
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.
[SecureContext, Exposed=Window]
interface CertificatePrincipal {
readonly attribute DOMString distinguishedNames;
};
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.