pkijs

PKIjs

Public Key Infrastructure (PKI) is the basis of how identity and key management is performed on the web today. PKIjs is a pure JavaScript library implementing the formats that are used in PKI applications. It is built on WebCrypto and aspires to make it possible to build native web applications that utilize X.509 and the related formats on the web without plug-ins.

Introduction

PKIjs is a library made in order to help people deal with (sometimes) complicated world of PKI-related data. For the moment it is quite easy to create a simple signature but hard to create PKCS#7 encoded signature. Easy to read a X.509 certificate but hard to parse values within it. PKIjs library will help all web applications (and chrome plug-ins) acomplish these and many other things. PKIjs was designed in such a way to make it easy to extended by users through a use of layered internal structures. There are many examples of using PKIjs and the number of examples will grow.

Numbers behind the library

• More than 16 000 lines of code and comments (PKIjs library + ASN1js library).
• More than 50 specialized pre-defined ASN.1 schemas.
• More than 50 specialized "helpers" working with almost all internal data (for example "GeneralName" type, all X.509 certificate extensions types, "revoked certificates" type, etc.).
• Everything that you need to work with all five major parts of PKI: X.509, PKCS#10, CMS, OCSP, Time-stamping.

Features of the library

• Fully object-oriented library. Inhiritence is using everywhere inside the lib;.
• Working with HTML5 data objects (ArrayBuffer, Uint8Array, Promises, WebCrypto, etc.).
• Has a complete set of helpers for working with types like:
  • GeneralName;
  • RelativeDistinguishedName;
  • Time;
  • AlgorithmIdentifier;
  • All types of ASN.1 strings, including "international" like UniversalString, UTF8String and BMPString (with help from ASN1js);
  • All extension types of X.509 certificates (BasicConstraints, CertificatePolicies, AuthorityKeyIdentifier etc.)
  • All "support types" for OCSP requests and responces;
  • All "support types" for Time-Stamping Protocol (TSP) requests and responces.
• Has own certification chain verification engine, purelly made on JavaScript with help from Promises and WebCrypto latest standard implementation;
• Working with all major PKI-related types ("minor" types are not mentioned here but there are huge number of such "minor types"):
  • X.509 certificates:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creatiion of a new X.509 certificate "from scratch";
    • Internal certificate chain validation engine.
  • X.509 "certificate revocation lists" (CRLs):
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new CRL "from scratch";
    • Validation of CRL signature;
    • Search inside CRL for specific revoked certificate.
  • PKCS#10 certificate request:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new PKCS#10 certificate request "from scratch";
    • Validation of PKCS#10 signature;
  • OCSP request:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new OCSP request "from scratch".
  • OCSP response:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new OCSP response "from scratch";
    • Validation of OCSP response signature.
  • Time-stamping request:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new Time-stamping request "from scratch";
    • Validation of Time-stamping request signature;
  • Time-stamping response:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new Time-stamping response "from scratch";
    • Validation of Time-stamping response signature
  • CMS Signed Data:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of a new CMS Signed Data "from scratch";
    • Validation of CMS Signed Data signature;
  • CMS Enveloped Data:
    • Parsing internal values;
    • Getting/setting any internal values;
    • Creation of CMS Enveloped Data and key exchange management comming soon;

Examples

            // #region Parsing raw data as a X.509 certificate object
            var asn1 = org.pkijs.fromBER(buffer);
            var cert_simpl = new org.pkijs.simpl.CERT({ schema: asn1.result });
            // #endregion

            // #region Creation of a new X.509 certificate
            cert_simpl.serialNumber = new org.pkijs.asn1.INTEGER({ value: 1 });
            cert_simpl.issuer.types_and_values.push(new org.pkijs.simpl.ATTR_TYPE_AND_VALUE({
                type: "2.5.4.6", // Country name
                value: new org.pkijs.asn1.PRINTABLESTRING({ value: "RU" })
            }));
            cert_simpl.issuer.types_and_values.push(new org.pkijs.simpl.ATTR_TYPE_AND_VALUE({
                type: "2.5.4.3", // Common name
                value: new org.pkijs.asn1.PRINTABLESTRING({ value: "Test" })
            }));
            cert_simpl.subject.types_and_values.push(new org.pkijs.simpl.ATTR_TYPE_AND_VALUE({
                type: "2.5.4.6", // Country name
                value: new org.pkijs.asn1.PRINTABLESTRING({ value: "RU" })
            }));
            cert_simpl.subject.types_and_values.push(new org.pkijs.simpl.ATTR_TYPE_AND_VALUE({
                type: "2.5.4.3", // Common name
                value: new org.pkijs.asn1.PRINTABLESTRING({ value: "Test" })
            }));

            cert_simpl.notBefore.value = new Date(2013, 01, 01);
            cert_simpl.notAfter.value = new Date(2016, 01, 01);

            cert_simpl.extensions = new Array(); // Extensions are not a part of certificate by default, it's an optional array

            // #region "BasicConstraints" extension
            var basic_constr = new org.pkijs.simpl.x509.BasicConstraints({
                cA: true,
                pathLenConstraint: 3
            });

            cert_simpl.extensions.push(new org.pkijs.simpl.EXTENSION({
                extnID: "2.5.29.19",
                critical: false,
                extnValue: basic_constr.toSchema().toBER(false),
                parsedValue: basic_constr // Parsed value for well-known extensions
            }));
            // #endregion 

            // #region "KeyUsage" extension 
            var bit_array = new ArrayBuffer(1);
            var bit_view = new Uint8Array(bit_array);

            bit_view[0] = bit_view[0] | 0x02; // Key usage "cRLSign" flag
            bit_view[0] = bit_view[0] | 0x04; // Key usage "keyCertSign" flag

            var key_usage = new org.pkijs.asn1.BITSTRING({ value_hex: bit_array });

            cert_simpl.extensions.push(new org.pkijs.simpl.EXTENSION({
                extnID: "2.5.29.15",
                critical: false,
                extnValue: key_usage.toBER(false),
                parsedValue: key_usage // Parsed value for well-known extensions
            }));
            // #endregion 

            cert_simpl.signatureAlgorithm.algorithm_id = "1.2.840.113549.1.1.5"; // RSA + SHA-1
            cert_simpl.signature.algorithm_id = cert_simpl.signatureAlgorithm.algorithm_id; // Must be the same value
            // #endregion 

        // #region Creation of a new CMS Signed Data 
        cms_signed_simpl = new org.pkijs.simpl.CMS_SIGNED_DATA({
            digestAlgorithms: [
                new org.pkijs.simpl.ALGORITHM_IDENTIFIER({ algorithm_id: "1.3.14.3.2.26" }) // SHA-1
            ],
            encapContentInfo: new org.pkijs.simpl.cms.EncapsulatedContentInfo({
                eContentType: "1.2.840.113549.1.7.1", // "data" content type
                eContent: new org.pkijs.asn1.OCTETSTRING({ value_hex: buffer })
            }),
            signerInfos: [
                new org.pkijs.simpl.CMS_SIGNER_INFO({
                    sid: new org.pkijs.simpl.cms.IssuerAndSerialNumber({
                        issuer: cert_simpl.issuer,
                        serialNumber: cert_simpl.serialNumber
                    }),
                    digestAlgorithm: new org.pkijs.simpl.ALGORITHM_IDENTIFIER({ algorithm_id: "1.3.14.3.2.26" }), // SHA-1
                    signatureAlgorithm: new org.pkijs.simpl.ALGORITHM_IDENTIFIER({ algorithm_id: "1.2.840.113549.1.1.5" }), // RSA + SHA-1
                })
            ],
            certificates: [cert_simpl]
        });

        return cms_signed_simpl.sign(privateKey, 0);
        // #endregion 

More examples could be found in "examples" folder.

Limitations

• Does not work with Internet Explorer's implementation of WebCrypto it is based on a old draft and also does not support all needed capabilities.
• Does not work with PolyCrypt it is based on a old version of WebCrypto and is buggy.
• You can use PKIjs in almost all browsers. Please check this page for information about WebCrypto browser support.

Suitability

At this time this library should be considered suitable for research and experimentation, futher code and security review is needed before utilization in a production application.

Related source code

• ASN1js project - in fact PKIjs will not work without ASN1js, it's neccessary part of the PKIjs project;
• C++ ASN1:2008 BER coder/decoder - the "father" of ASN1js project;
• Freely available ASN.1:2008 test suite - the suite which can help you to validate (and better understand) any ASN.1 coder/decoder;

How to use PKIjs with Node.js

!!! WARNING !!! Currently there is no "polyfill" of WebCrypto in Node.js. Thus you will not be able to use signature / verification features of PKIjs in Node.js programs.

In order to use PKIjs you will also need ASN1js plus node.extend package.

    var merge = require("node.extend");

    var common = require("asn1js/org/pkijs/common");
    var _asn1js = require("asn1js");
    var _pkijs = require("pkijs");
    var _x509schema = require("pkijs/org/pkijs/x509_schema");

    // #region Merging function/object declarations for ASN1js and PKIjs 
    var asn1js = merge(true, _asn1js, common);

    var x509schema = merge(true, _x509schema, asn1js);

    var pkijs_1 = merge(true, _pkijs, asn1js);
    var pkijs = merge(true, pkijs_1, x509schema);
    // #endregion 

After that you will ba able to use ASN1js and PKIjs via common way:

        // #region Decode and parse X.509 cert 
        var asn1 = pkijs.org.pkijs.fromBER(certBuffer);
        var cert;
        try
        {
            cert = new pkijs.org.pkijs.simpl.CERT({ schema: asn1.result });
        }
        catch(ex)
        {
            return;
        }
        // #endregion 

License

Copyright (c) 2014, GMO GlobalSign All rights reserved.

Author 2014, Yury Strozhevsky.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.