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

UNDER CONSTRUCTION

Some changes such as Certificate class or CertificationRequest class are not yet described in this document. In such case, please see API document or test cases to understand the 9.0.0 updates. Sorry for patience.

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

TBD

CSR parsing

TBD

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