Send feedback to mailto:public-webcrypto@w3.org (archives), or file a bug (see existing bugs).
Copyright © 2013 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification describes a JavaScript API for performing certificate management operations in web applications, such as issuing, updating, revoking and validating a certificate.
the table of contents are defined by Working Group Charter and email comments.
definition of WebIDL will be added after getting consensus for table of contents.
HongGilDong want to issue certificate that will be used online banking.
he visit physical bank branch and retrieve reference number and approval code by face to face verification of bank staff. the reference number is used to track certificate enrollment process for multiple days.
HongGilDong visit bank website (ra.gangnambank.com).
he generate key pair and send the public key, reference number, approval code and other parameters to bank RA(Registry Authority) center by CMP of RFC4210.
bank RA server forward the request to CA and return the certificate signed by CA to user agent of HongGilDong.
when he want to wire fund online, he enter some verification codes (OTP, password or other authentication methods promised between bank and account holder).
he generate digital signature for agreement document with his private key binded to certificate issued by trusted CA also he envelop the signed document with certificate of bank and send enveloped message to bank.
when he want to revoke certificate, he generate digital signature for revoke request document with his private key also he envelop the signed document with certificate of bank. and send enveloped message to bank.
bank forward the revoke request to CA.
CA add the certificate to CRL that will be check later by CRL Distribution Point of certificate.
The Web Certificate API based on the certificate management protocol follows by RFC4210.
this specification focus on user agent side of RFC4210 CMP
the specification is trying to keep existing CA services with minor changes
Web Certificate API defines the request and response parameters and processed between user agent and CA service providers
The following figure illustrates the operational flow of certificate menagement. The UA always requests one of the certificate management operation to a CA server by sending a request message. CA server then processes the request message and sends the result of oepration in a response message back to the UA. The UA handles the response message to retrieve the status and a certificate if necessary and then it optionally sends a confirmation message to CA server to notify the end of an operation.CertMessage is the object that will contain a return value when the request of cmp is generated. The message contained in this object is sent to CA server for certificate oepration.
Interface CertMessage {
readonly attribute any msgType;
readonly attribute any msgID;
readonly attribute any message:
};
msgType - this indicates which certificate oepation is contained in this message.
msgID - identifier that identify any related messages during oepration
message - text based message that is encoded according to msgType
CertResult is the object that will contain a return value when the response of cmp is received from a CA Server. This object contains the result of CA operation that is requested by UA.
Interface CertResult {
readonly attribute any status;
readonly attribute any msgID;
readonly attribute any certificate:
};
status - this indicates the result of CA operation requested by UA.
msgID - identifier that identify any related messages during oepration
certificate - a certificate that is issued or updated by CA server
Cert is the object that requests a certificate operation to CA server and handles a response message from the server.
enum ReqType {
// RFC 4210 Certificate Management Protocol.
"cmp",
// Certificate Management protocol using CMS.
"cmc",
// PKCS#10 type Certificate signing request.
"pkcs10",
};
Interface Cert {
CertMessage requestCert (ReqType reqType, KeySpec keySpec, DOMString refCode, DOMString authKey);
CertMessage updateCert (ReqType reqType, KeySpec keySpec, DOMString certID, DOMString keyPass);
CertMessage revokeCert (ReqType reqType, DOMString certID, DOMString keyPass);
CertResult handleResp (CertMessage certMessage);
CertMessage genConfirm (DOMString msgID, DOMString certID, DOMString keyPass);
}
This method allows UA to request a certificate to CA. This method returns base64 encoded ASN.1 encoded initial request message if cmp is used.
Input parameters:
This method allows UA to renew a certificate to CA. This method returns ASN.1 encoded initial request message if cmp is used.
Input parameters:
Return value:
This method allows UA to renew a certificate to CA. This method returns ASN.1 encoded initial request message if cmp is used.
Input parameters:
Return value:
This method handles a response message sent from CA Server.
Input parameters:
Return value:
This method generates confirmation message required in CMP protocol sending to CA server that confirms certificate operation is successfully finished. This method is optional since some type of certificate management is not needed
Input parameters:
Return value:
certificate validation is added on to public key verification.
certificate chain validation validate certificate chains up to the trusted RootCA.
when validating certificate, certificate revocation list will be optionally checked.
when the full CRL size is too big to download on low speed network environment, CRLDP can be used for effective CRL checking.4.2.1 CRL Distribution Point
Online Certificate Status Protocol(OCSP) can be optionally used to validate certificate.
Same Origin Policy is base security policy of WebCrypto API
to keep the backward compatibility, some conditional exceptions are required but it does not mean the multiple connections to multiple origins
the exceptions are only for accessing private keys that is binded to some origin initiated from different origin when the faired certificate is valid
the exceptions of same-origin policy can be allowed by following conditions
Certificate KeyStorage should be interoperable with existing TLS Key Storage
to keep the backward compatibility, when the certificate is installed into user agent, it will be listed in TLS Key Storage of user agent
but the certificate operations will be restricted by the KeyUsage defined in certificate inside.
when the certificate and private key pair is inserted via PKCS#11 interface into TLS Key Storage, it also can be used by webcrypto API with valid KeyUsage