Tutorial for extensions when generating certificate

Extensions can be specified as JSON object when generating a certificate.

This document describes samples for extensions.

Common to extensions

"extname" member shall be specified. "critical" flag is OPTION.

{ extname: "NAME-OF-EXTENSION",
  critical: true, // OPTION: critical flag can be specified
  ... extension values ... }

Basic Constraints

{ extname: "basicConstraints",
  critical: true,
  cA: true,     // OPTION. "false" can also be specified.
  pathLen: 2 }  // OPTION

Key Usage

{ extname: "keyUsage", names: ["digitalSignature", "nonRepudiation"] } // don't need to care ordering

Key usage value can also be specified by DERBitString parameters.

{ extname: "keyUsage", bit: "11" }
{ extname: "keyUsage", array: [true, true, false, true] }

CRL Distribution Points

{ extname: "cRLDistributionPoints",
  array: [
    {fulluri: "http://repository.example.com/CA1.crl"}
  ] }

Authority Info Access

{ extname: "authorityInfoAccess",
  array: [
    {ocsp: 'http://ocsp.example.org'},
    {caissuer: 'https://repository.example.org/ca1.crt'}  
  ] }

Subject Key Identifier

You can specify "kid" by PEM string of certificate or public key or key object which can be accepted by KEYUTIL.getKey method. Its key ID value will be calculated automatically by the method specified in RFC 5280 section 4.2.1.2 (1).

{ extname: "subjectKeyIdentifier", kid: ...PEM-OF-CERT-OR-PUBKEY... }
{ extname: "subjectKeyIdentifier", kid: ...KEYOBJECT... }

Otherwise you can explicitly specify key identifier value by hexadecimal or raw string which can be accepted by DEROctetString class.

{ extname: "subjectKeyIdentifier", hex: "1abd23f..." }
{ extname: "subjectKeyIdentifier", str: "\x3f\xa1..." }

Authority Key Identifier

AuthorityKeyIdentifier has three optional fields.

AuthorityKeyIdentifier ::= SEQUENCE {
  keyIdentifier             [0] KeyIdentifier           OPTIONAL,
  authorityCertIssuer       [1] GeneralNames            OPTIONAL,
  authorityCertSerialNumber [2] CertificateSerialNumber OPTIONAL  }

As for "keyIdentifier", the same members as "SubjectKeyIdentifier" are available. For "authorityCertIssuer" and "authorityCertSerialNumber", you can specify them by "isscert" member with certificate PEM string.

{ extname: "authorityKeyIdentifier",
  kid: "-----BEGIN CERTIFICATE...",
  isscert: "-----BEGIN CERTIFICATE..." }

Otherwise you can explicitly specify them by "issuer" and "sn" members as follows:

{ extname: "authorityKeyIdentifier",
  kid: "-----BEGIN CERTIFICATE...",
  issuer: { ldapstr: "CN=CA1,O=Test,C=JP" },
  sn: { hex: "1fda3d..." } }

Subject Alt Name and Issuer Alt Name

SubjectAltName and IssuerAltName have the same style of parameters.

{ extname: "subjectAltName", // for IssuerAltName, "issuerAltName" shall be specified
  array: [
    {rfc822: "[email protected]"},    // [1] rfc822Name
    {dns: "example.org"},           // [2] dNSName
    {dn: "/C=JP/O=Test"},           // [4] Name (i.e. X.500 Name)
    {dn: {str: "/C=JP/O=Test"}},    // [4] Name
    {dn: {ldapstr: "O=Test,C=JP"}}, // [4] Name
    {dn: {certissuer: "-----BEGIN CERTIFICATE..."}},  // [4] Name (issuer name of certificate)
    {dn: {certsubject: "-----BEGIN CERTIFICATE..."}}, // [4] Name (subject name of certificate)
    {uri: "http://example.net/"},   // [6] uniformResourceIdentifier
    {ip: "192.168.1.1"},            // [8] iPAddress (IPv4 address)
    {ip: "2001:db4::4:1"}           // [8] iPAddress (IPv6 address)
  ] }

[0] otherName, [3] x400Address, [5] ediPartyName and [8] registeredID are not supported yet.

Certificate Policies

{ extname: "certificatePolicies",
  array: [ // array of PolicyInformation
    { policyoid: "1.2.3.4.5",
      array: [ // PolicyQualifiers
        { cps: "https://example.com/repository" },
        { unotice: {
          noticeref: { // CA SHOULD NOT use this by RFC
            org: {type: "ia5", str: "Sample Org"},
            noticenum: [{int: 5}, {hex: "01af"}]
          },
          exptext: {type: "ia5", str: "Sample Policy"}
        } }
      ]
    },
    { policyoid: "0.1.2.3.4" }
  ]
}

OCSP No Check

OCSPNoCheck extension is generally used in OCSP responder certificate. It doesn't require any other parameters.

{ extname: "ocspNoCheck" }

Adobe Time Stamp

This extension is used in Adobe CDS certificate to specify timestamp service URL.

{ extname: "adobeTimeStamp",
  uri: "http://tsa.example.com/",
  reqauth: true }

Subject Directory Attributes

This extension is used in a qualified certificate. All of supported attributes are in this example.

{ extname: "subjectDirectoryAttributes",
  array: [
    { attr: "dateOfBirth", str: "19701231230000Z" },
    { attr: "placeOfBirth", str: "Tokyo" },
    { attr: "gender", str: "F" },
    { attr: "countryOfCitizenship", str: "JP" },
    { attr: "countryOfResidence", str: "JP" }
  ] }

Private Extension

If you want to specify a private extension PrivateExtension class can be used. The "extn" member shall have ASN1Util.newObject parameter to specify arbitrary ASN.1 object.

{ extname: "1.2.5.6" // any extension OID
  extn: {seq: [{prnstr:"abc"},{utf8str:"def"}]} }

CRL Number

This extension may be specified in a CRL extension.

{ extname: "cRLNumber", 
  num: {"int": 12345} }

CRL Reason

This extension may be specified in CRL entry extension or single OCSP response.

{ extname: "cRLReason",
  code: 2 } // (2) cACompromise

OCSP Nonce

This extension may be specified in OCSP response extension.

{ extname: "ocspNonce",
  hex: "12ab..." }