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.
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.
- 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.
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": "[email protected]"}]},
{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.
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": "[email protected]"}]},
{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.
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/[email protected]"},
sbjpubkey: kp.pubKeyObj, // you can also set PEM public key string
extreq: [{extname:"subjectAltName",array:[{rfc822:"[email protected]"}]}],
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.
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/[email protected]"},
sbjpubkey: kp.pubKeyObj, // you can also set PEM public key string
extreq: [{extname:"subjectAltName",array:[{rfc822:"[email protected]"}]},
{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 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.
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.
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/[email protected]"}
// or by RFC 2253 LDAP format string
{"ldapstr": "[email protected],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:"[email protected]",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.
- 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
- 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
- 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
- X509.getExtExtKeyUsageName
- X509.getExtAIAInfo
- X509.getExtSubjectAltName2