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

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.

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