Skip to content

NOTE jsrsasign 8.0.x to 9.0.0 Certificate and CSR API migration guide

Jump to bottom
Kenji Urushima edited this page Aug 20, 2020 · 16 revisions

You can also see API document or test cases to understand the 9.0.0 updates.

INTRODUCTION: 9.0.0 update concept

Before 8.0.24 Certificate and CSR parser and generator have not worked together. Further more, they didn't have API consistency. In version 9.0.0, such issue will be solved.

general migration guide

  • When you codes don't use certificate and CSR parsing and generation, you can update to 9.0.0.
  • When you codes use certificate, certificate extension and CSR APIs without backward compatibility, you need to modify your codes.

certificate generation

In 8.0.24 or before, X509Util.newCertPEM method may be used. In 9.0.0 or later you don't need to use it. Just you can use Certificate class constructor as follows:

var cert = new KJUR.asn1x509.Certificate({
 version: 3,
 serial: {hex: "2345..."},
 sigalg: "SHA256withRSA",
 issuer: {str: "/C=JP/O=CA1"},
 notbefore: "011231235959Z",
 notafter:  "221231235959Z",
 subject: {str: "/CN=User1"},
 sbjpubkey: "-----BEGIN PUBLIC KEY...",
 ext: [
  {extname: "keyUsage", names:["digitalSignature"], critical:true},
  {extname: "subjectAltName", array:[{"rfc822": "user1@example.com"}]},
  {extname: "cRLDistributionPoints", array:[{fulluri:"https://example.com/ca1.crl"}]}
 ],
 cakey: "-----BEGIN PRIVATE KEY..."
});
var pem = cert.getPEM();

Note that no need to use TBSCertificate class. Argument parameter of Certificate class constructor is almost the same as TBSCertificate. The only difference is the "cakey" attribute.

certificate parsing

In 8.0.24 or before, there is no method to get entire certificate parameters. We need to develop such method by combining methods to get each fields. In 9.0.0 or later, we can use X509.getParam method as follows:

var x = new X509();
x.readCertPEM("-----BEGIN CERTIFICATE...");
console.log(x.getParam());
{
 version: 3,
 serial: {hex: "2345..."},
 sigalg: "SHA256withRSA",
 issuer: {str: "/C=JP/O=CA1"},
 notbefore: "011231235959Z",
 notafter:  "221231235959Z",
 subject: {str: "/CN=User1"},
 sbjpubkey: "-----BEGIN PUBLIC KEY...",
 ext: [
  {extname: "keyUsage", names:["digitalSignature"], critical:true},
  {extname: "subjectAltName", array:[{"rfc822": "user1@example.com"}]},
  {extname: "cRLDistributionPoints", array:[{fulluri:"https://example.com/ca1.crl"}]}
 ],
 sighex: "1234abcd..."
}

As you see above, the result of getParam() method can be passed to Certificate class constructor described above.

CSR generation

In 8.0.24 or before, CSRUtil.newCSRPEM is used to generate CSR(certificate signing request). In 9.0.0 or later, CertificationRequest class constructor can be used instead:

var kp = KEYUTIL.generateKeypair("RSA", 2048);
var csr = new KJUR.asn1.csr.CertificationRequest({
  subject: {str: "/C=JP/O=Test/CN=user1@example.com"},
  sbjpubkey: kp.pubKeyObj,  // you can also set PEM public key string
  extreq: [{extname:"subjectAltName",array:[{rfc822:"user1@example.com"}]}],
  sigalg: "SHA256withRSA",  // you can also set PEM private key string
  sbjprvkey: kp.prvKeyObj
});
var pem = csr.getPEM();

As for "extensionRequest" attribute, you can add any extension parameter in the "extreq" parameter. As though in 8.0.24 or before, only "subjectAltName" extension can be used.

CSR parsing

In 8.0.24 or before, parsing CSR can be done by CSRUtil.getInfo class however its result JSON object can't be passed to CSRUtil.newCSRPEM. So you need to modify the result and pass to newCSRPEM. In 9.0.0 or later, we can use CSRUtil.getParam method instead:

var json = KJUR.asn1.csr.CSRUtil.getParam("-----BEGIN CERTIIFCATE REQUEST...");
console.log(json);
{
  subject: {str: "/C=JP/O=Test/CN=user1@example.com"},
  sbjpubkey: kp.pubKeyObj,  // you can also set PEM public key string
  extreq: [{extname:"subjectAltName",array:[{rfc822:"user1@example.com"}]},
           {extname:"extKeyUsage",array:["clientAuth"]}],
  sigalg: "SHA256withRSA",  // you can also set PEM private key string
  sighex: "1234abcd..."
}

The result JSON object can be passed to CertificationRequest class constructor.

certificate extension JSON parameter format

Certificate extension JSON parameter format have been changed in 9.0.0. In 8.0.24 or before, "basicConstraints" extension will be as following:

{"basicConstraints": {"critical": true, "cA": true, "pathLen": 3}}

In 9.0.0 or later, it will be:

{"extname": "basicConstraints", "critical": true, "cA": true, "pathLen": 3}

Note that all extensions have "extname" property for extension name and JSON parameter stop to use nest.

array of certificate extension parameters

New method to parse certificate or CSR extensions have been introduced in 9.0.0. That is X509.getExtParamArray method. It can be used for both certificate and CSR.

add new X500Name parameter representation

In 8.0.24 or before, X500Name JSON parameter used in such as subject or issuer name or subjectAltName have been following

// by OpenSSL compat format string
{"str": "/C=JP/O=User1/CN=user1@example.com"}
// or by RFC 2253 LDAP format string
{"ldapstr": "CN=user1@example.com,O=User1,C=JP"}
// or hexadecimal string of X500 name ASN.1 structure
{"hex": "30..."}

In "str" or "ldapstr" representation, DirectoryString type such as UTF8String or PrintableString defined automatically. So to specify DirectoryString type explicitly we have needed to use "hex" representation before.

In 9.0.0 or later, new 3-tuple array representation have been introduced. Here is example:

{"array": [
 [{type:"C",value:"JP",ds:"prn"}],
 [{type:"O",value:"User1",ds:"utf8"}],
 [{type:"CN",value:"user1@example.com",ds:"ia5"}]
]}

3-tuple represents AttributeTypeAndValue ASN.1 structure and has "type", "value" and "ds" property. RDN will be array of 3-tuple and it can also handle multi-valued RDN. X500Name will be 3-tuple array of array. Then it can specify Directory string type explicitly. When "array", "str" and "hex" have been specified in the JSON parameter at one time, "array" have priority.

updated APIs without backward compatibility

  • return value format of X509.getExtAuthorityKeyIdentifier
  • return value format of X509.getExtSubjectKeyIdentifier
  • return value format of X509.getExtSubjectAltName
  • KJUR.asn1.x509.CertificatePolicies constructor parameter
  • KJUR.asn1.x509.AuthorityInfoAccess constructor parameter

updated APIs with backward compatibility

  • return value format of X509.getExtKeyUsageString (decipherOnly bugfix)
  • return value format of X509.getExtKeyUsageBin (decipherOnly bugfix)
  • return value format of X509.getBasicConstraints
  • KJUR.asn1.x509.BasicConstraints constructor parameter
  • KJUR.asn1.x509.DistributionPointName constructor parameter
  • KJUR.asn1.x509.DistributionPoint constructor parameter
  • KJUR.asn1.x509.CRLDistributionPoints constructor parameter

newly added APIs

  • X509.getExtKeyUsage
  • X509.getExtCertificatePolicies
  • X509.getExtCertificatePolicies
  • X509.getPolicyInformation
  • X509.getPolicyQualifierInfo
  • X509.getUserNotice
  • X509.getDisplayText
  • X509.getIssuerAltName
  • X509.getExtExtKeyUsage
  • X509.getExtCRLDistributionPoints
  • X509.getDistributionPoint
  • X509.getDistributionPointName
  • X509.getExtAuthorityInfoAccess

deprecated APIs

  • X509.getExtExtKeyUsageName
  • X509.getExtAIAInfo
  • X509.getExtSubjectAltName2

jsrsasign TOP | github | Wiki | DOWNLOADS | TUTORIALS | API REFERENCE | Online Tool | DEMO | NODE TOOL | AddOn | AddOn2 | DONATE

Clone this wiki locally