API

Abstract

This Javascript API defines an origin-specific certificate discovery API which provides access to its associated cryptographic keys for use with the Web Cryptography API. The user agent will prompt the user in a user agent specific manner for permission to the returned certificates. The certificates are queried using its attributes (e.g.: issuer, key usage, subject, ...). The associated keys can be used to perform basic cryptographic operations in web applications, such as hashing, signature generation and verification, and encryption and decryption, using the Web Cryptography API.

See use cases for a list of use cases.

Status of this API

This API is still in an early phase and was started to keep the discussion about getting access to smart cards and USB security tokens on the web active. We are welcoming any comments and contributions.

X500Principal

The X500Principal object represents a X.500 Principal. X500 principals are represented by distinguished names ("CN=Steve Hardcastle-Kille, OU=Computer Science, O=University College London, C=GB").

name

string representation of an X.500 distinguished name (ex: "CN=Steve Hardcastle-Kille, OU=Computer Science, O=University College London, C=GB").

encodedName

The distinguished name in ASN.1 DER encoded form.

interface X500Principal {
    readonly attribute DOMString name; // string representation of an X.500 distinguished name (ex: "CN=Steve Hardcastle-Kille, OU=Computer Science, O=University College London, C=GB").
    readonly attribute ArrayBufferView encodedName; //distinguished name in ASN.1 DER encoded form
}

X509Certificate

The X509Certificate object represents an X.509 certificate which provides access to its properties and keys. The returned keys are of the Key type defined in the Web Cryptography API.

interface X509Certificate {
    readonly attribute Algorithm algorithm;
    readonly attribute X500Principal issuerX500Principal;
    readonly attribute Date notAfter;
    readonly attribute Date notBefore;
    readonly attribute Key publicKey;
    readonly attribute Key? privateKey;
    readonly attribute DOMString serialNumber; // JS doesn't have a bigInt at the moment
    readonly attribute ArrayBufferView signature;
    readonly attribute X500Principal subjectX500Principal;
    readonly attribute integer version;
    readonly attribute boolean[] keyUsage; // See rfc5280 for more information
    readonly attribute DOMString[]? extendedKeyUsage; // See rfc5280 for more information
    // Do we need checkValid functionality, if so does it check CRL? 
}

Algorithm parameter extions for signing precomputed hashes.

In some cases when you are using hardware keys, you want to offload the calculation of the hash to the main CPU and don't do it on the hardware containing the key, because the computation power of the main CPU is much higher then the on the hardware key.

The RsaSsaParams, RsaPssParams, EcdsaParams and HmacParams dictionaries defined in the Web Cryptography API are extended with a SignInput property, which indicates if the input is already a digest or plain text. If the input entry is omitted, the input is considered to be in plain text.

enum SignInput {
    "plaintext",
    "digest"
};

// extend RsaSsaParams dictionary with
dictionary RsaSsaParams : AlgorithmParameters {
    SignInput? input;
};

// extend RsaPssParams dictionary with
dictionary RsaPssParams : AlgorithmParameters {
    SignInput? input;
};

// extend EcdsaParams dictionary with
dictionary EcdsaParams : AlgorithmParameters {
    SignInput? input;
};

// extend HmacParams dictionary with
dictionary HmacParams : AlgorithmParameters {
    SignInput? input;
};

CertificateOperation interface

interface CertificateOperation : EventTarget {
    readonly attribute any result;

    [TreatNonCallableAsNull] attribute Function? onerror;
    [TreatNonCallableAsNull] attribute Function? oncomplete;
};

CertificateExporter interface

interface CertificateExporter : CertificateOperation {
}

X509CertificateSelector interface

Note: The user agent will prompt the user in a user agent specific manner for permission to provide the entry script's origin access to the returned certificates.

interface X509CertificateSelector : CertificateOperation {
}

X509CertificateSelectorParams

dictionary X509CertificateSelectorParams {
    X500Principal[]? authorities; // The certificate has one of the authorities in his certificate chain
    boolean? certificateValid;
    Date? certificateValidDate; // if not set use current date
    boolean[]? keyUsage; // See rfc5280 for more information
    DOMString[]? extendedKeyUsage; // See rfc5280 for more information
    X500Principal? issuer;
    boolean? privateKeyValid;
    Date? privateKeyValidDate; // if not set use current date
    Algorithm? publicKeyAlgorithm;
    DOMString? serialNumber; // JS doesn't have a bigInt at the moment
    X500Principal? subject;
}

Crypto object extensions

The Crypto interface (defined in the Web Cryptography API) is extended with methods to create X500Principal, X509CertificateSelector and CertificateExporter objects.

See note in section x509certificateselector interface for security constraints on accessing certificates.

interface Crypto {
    X500Principal createX500Principal(ArrayBufferView encodedName); //  distinguished name in ASN.1 DER encoded form
    X500Principal createX500Principal(DOMString name); // string representation of an X.500 distinguished name (ex: "CN=Steve Hardcastle-Kille, OU=Computer Science, O=University College London, C=GB").
    CertificateExporter createX509CertificateExporter(X509Certificate certificate);
    X509CertificateSelector createX509CertificateSelector(X509CertificateSelectorParams params);
}