This document defines APIs for signing the message by the user certificate issuing from the certificate authority for SSL communications. It provides cryptographic functions like handling the user certificate, secure login/logout and verifying the authentity of data i.e. digital signatures.

Introduction

WebCrypto Object implements an interface exposed by a script engine that allows scripts to perform PKI based functionality, such as issuing the user certificate, signing the message and session authentication in the only HTTPS connection.

Some simple code to do signing message from the user certificate. 

	var crypto = new WebCrypto();

	function login() {
	    var crypto = new WebCrypto();
	    result = crypto.login(); // Launching prompt window to select user certificate
	}

	function generateCSR() {
	    with (document.forms[0]) {
	        crmfObject = crypto.generateRequest(
                "CN=" + name.value, password.value,
                "","","", 1024, null, "rsa-dual-use");
	    cert_request.value = crmfObject.request;
            submit();
            }
        return false;
       }

	function signText() {
	    var foo = crypto.signText("Transfer USD1 to Some bank", "ask");
	    // Launching prompt window to select user certificate
	}

	function importCertificate() {
	    keypair = crypto.exportKeypair("PKCS#12");
	    // Launching prompt window to select p12 file from file system or SmartCard.
	}

Requirements and use cases

This specification must meet the following requirements:

Secure login/logout
Choose the client certificate issued by its CA in specific user authentication.
Generate a certificate request
Generates a private key and creates a CRMF Request object and imports issued certificate
Signing specific texts or XML
Given a plaintext and a public key, return the corresponding cyphertext.
Given a cyphertext and a private key, return the corresponding plaintext.
Export a public/private key pair
Export certificates from the keystore to file formats, SmartCard or USB token
Import a public/private key pair
Load certificates from the keystore, SmartCard or USB token if the corresponding key is found there.
Load SmartCard or USB tocken
Events for loading the certificate from SmartCard or HSM based USB token

This specification must meet the following use cases:

Issuing client certificate
  1. A User fills out enrollment form and calls key generation method (as like Mozilla's generateCRMFRequest)
  2. The User agent generates encrypted private key wrapped with public key and signed certificate request with text string from the script (possibly containing naming or enrollment information). It's same of the action of keygen.
  3. The User agent returns signed certificate request into the script and submits it into the certificate authority. The CA creates and signs certificates.
  4. The CA sends certificates back to the user (as like Mozilla's importUserCertificates) and user agent saves it into its keystore.
Signing and verifying text or XML
  1. A User can see important messages to be signed by oneself and offers them to a bank service site or one's company site.
  2. The User agent generates signed messages by user chosen certificate and send HTTPS server issuing the user certificate.
Secure login/out in HTTPS server
  1. A User can log in or log out HTTPS web services with the user certificate
  2. The User agent generates protected session key in log-in and destroys in log out.
Import/Export keypair from/to keystore

The WebCrypto Interface

WebCrypto Object implements an interface used by scripts to programmatically secure communications to their HTTPS server with the user certificate. 

interface WebCrypto {

  readonly attribute DOMString        version;
  attribute boolean         enableSmartCardEvents;

  DOMString                 random(in long numBytes);

  DOMString                 generateCertRequest(in DOMString requestedDN,
                                           in DOMString regToken,
                                           in boolean authenticator,
                                           in DOMString escrowAuthorityCert,
                                           in DOMString finalCode,
                                           in DOMString keySize,
                                           in DOMString keyParams,
                                           in DOMString keyGenAlgorithm);

  DOMString                 importUserCert(in DOMString nickname,
                                           in DOMString cmmfResponse,
                                           in boolean doForcedBackup);

  DOMString                 viewCertInfo(in DOMString nickname);
  DOMString                 validateUserCert(in DOMString nickname);

  DOMString                 signText(in DOMString stringToSign,
                                     in DOMString caOption);

  DOMString                 decryptText(in DOMString stringTodecrypt,
                                     in DOMString caOption);

  DOMString                 verifySign(in DOMString stringToverify,
                                     in DOMString caOption);
 
  void                      importKeypair(in DOMString cipherFlag);
  void                      exportKeypair();

  void                      validateUserCert();
  void                      revokeUserCert();


  attribute boolean         login();
  attribute boolean         logout();
};

Issuing the user certificate

generateCertRequest method

The generateCertRequest method generates a sequence of certificate requests that has multiple requests. The user agent must make one request for each key pair that is generated.

When the generateCertRequest("requestedDN", "regToken", "authenticator", "escrowAuthorityCert", "finalCode", keySize, "keyParams", "keyGenAlgorithm") method is invoked, the user agent must run these steps:

  1. Let requestedDN be a RFC 1485 formatted Distinguished Names to include in the certificate request.
  2. Let regToken be a value used to authenticate the user to the certificate authority.
  3. Let authenticator be a value that the user can authenticate with in the future when their private key is not available. Can be used for key recovery or revocation requests.
  4. The escrowAuthorityCert specifies which KRA certificate should be used to wrap the private key being escrowed. If this value is NULL, then no key escrow will be performed.
  5. If keySize exists, let be the size in bits of the key to generate.
  6. The keyParams be an optional algorithm dependent parameter value.
  7. Let keyGenAlgorithm be encryption algorithm the generated key will support. Acceptable values are listed in Definitions of mechanism flag and algorithm.
  8. The user agent prompts the user to be presented with a key generation dialog. that describes the key generation process and gives the user the opportunity to cancel the operation.
  9. If finalCode exists, the certificate request object is returned to this Javascript method.

importUserCert method

The importUserCert method loads certificates into the keystore or SmartCard if the corresponding key is found there.

viewCertInfo method

The viewCertInfo method shows detail informations of the specific certificate of given nickname.

validateUserCert method

The validateUserCert method checks validity of the specific certificate of given nickname by communication to Certificate Revocation List or valid OCSP server.

Signing messages

This section non-normative

signText method

The signText method generates digitally signed encrypted messages by selected the user certificate given text strings. When the signText("stringToSign", "caOption") method is invoked, the user agent must run these steps:

  1. Let stringToSign be the string that the user want to sign. It can be the string, json or XML format. If stringToSign indicates document ID for specific form, the user agent generates QUERY_STRING variables from form.
  2. If caOption is "ask", the user agent must presented to the user in a dialog box to show human-readable text to be signed and select the user certificate. In case of "auto" for the caOption parameter, it indicates the user agent selects a signing certificate automatically from those available in the certificate keystore.
  3. In all cases the user may choose either to cancel the signing operation by clicking "Cancel" or to approve the operation by clicking "OK". If the user approves the operation, the user agent asks for the password to the certificate keystore. If the user enters the correct password, this method signs the specified string and returns the signed string.

decryptText method

The decryptText method decrypts digitally signed messages from the server with the user certificate. When the decryptText("stringTodecrypt", "caOption") method is invoked, the user agent must run these steps:

  1. Let stringTodecrypt be the string that the user want to decrypt.
  2. If caOption is "ask", the user agent must presented to the user in a dialog box to show human-readable text to be signed and select the user certificate. In case of "auto" for the caOption parameter, it indicates the user agent selects a certificate to decrypt given cipher text automatically from those available in the certificate keystore.
  3. In all cases the user may choose either to cancel the signing operation by clicking "Cancel" or to approve the operation by clicking "OK". If the user approves the operation, the user agent asks for the password to the certificate keystore. If the user enters the correct password, this method decrypts specific cipher text and returns the plain text.

veryfySign method

The veryfySign method verifies digitally signed encrypted message if the integrity is guranteed or not.

Key handling

This section non-normative

importKeypair method

This importKeypair method import a key pair into a keystore from PKCS #12 or PEM bundle file.

  1. Th user selects the folder where the required PKCS #12 or PEM bundle file is stored and clicks on the required PKCS #12 or PEM bundle file.
  2. If the selected file was a PEM bundle containing encrypted private keys, one or more Password for Private Key dialogs will appear, one fore each such key.
  3. The method can call directly the native user interface of the browser specific function for importing keypair.

exportKeypair method

This section non-normative

Secure user authentication

This section non-normative

login attribute

logout attribute

Miscellaneous

version attribute

enableSmartCardEvents attribute

The enableSmartCardEvents attribute listens for SmartCard insertion and removal events. By setting webcrypto.enableSmartCardEvents to true, the system is ready for listening of these events. Two smart card related events are generated "smartcard-insert" when SmartCards are inserted, and "smartcard-remove" when SmartCards are removed. 

function onSmartCardChange() {
window.location.reload();
}

function register() {
window.crypto.enableSmartCardEvents=true;
document.addEventListener("smartcard-insert",onSmartCardChange,false);
document.addEventListener("smartcard-remove",onSmartCardChange,false);
}

function deregister() {
document.removeEventListener("smartcard-insert",onSmartCardChange,false);
document.removeEventListener("smartcard-remove",onSmartCardChange,false);
}

random method

Guidelines for user interface

This guideline is to maintain the consistency of user interfaces for avoiding confusion of the user between the user agent.

Login with the user certificate

When the user logs in the HTTPS server, the user agent shows the important information of HTTS server i.e. the URL, company name and basic location informations.

The user agent should avoid pop-up style window to select the user certificate.

Signing text the user certificate

When the user signs the text with the user certificate, the user agent shoud show signing text to the user.

The user agent should avoid pop-up style window to select the user certificate.

Security

This section explains security considerations for this specification.

  1. All of functions in this specification must be operated under HTTPS-forced connection.
  2. Some important methods must be processed after browser-based key protection method as like Firefox's master password.
  3. Before signining request, the user must be logged in this same domain with the same client certificate issued by the valid certificate autority.
  4. Signing request must be done by the only user certificate which the extension of certificate Key Usage is "Signing".
  5. Signing requests must be restricted to the top level content (i.e. not frames) to ensure origin of the request in URL of location bar.
  6. It must be included the content domain information in the signed message for the guarantee of an data integrity.

Acknowledgements

This specification is the result of many discussions in W3C HTML5 and Web Applications Workging Group and many people helped to make this including Anders Rundgren, Lucas Adamski, Kai Engert, Bob Relyea, Amax Guan, Gen Kanai, Minkyu Shin, Dongsan Lee and Jungsik Shin.

Related Specifications

RFC 1485
A String Representation of Distinguished Names
RFC 4211
the Internet X.509 Public Key Infrastructure Certificate Request Message Format (CRMF), defines a certReqMessage. The object returned by generateCRMFRequest() contains one of those.
HTML5
keygen element to key-pair generator/input control
HTML5 Web Workers
1.2.6 Providing libraries Suppose that a cryptography library is made available