Skip to main content

%Net.JSON.JWK

class %Net.JSON.JWK extends %Library.RegisteredObject

This class provides methods to create JSON Web Keys, as defined in RFC 7517, and convert between the JSON Web Key format and other key representation formats.

Method Inventory

Methods

classmethod Create(alg As %String, secret As %String = "", Output privJWK As %DynamicObject, Output pubJWK As %DynamicObject) as %Status
This method creates a new public/private JSON Web Key (JWK) pair for the given algorithm.

Input parameters:
  • alg - The algorithm for which to create the JWK.
  • secret - An optional shared secret to be used as the key. If this is omitted, a new secret will be generated. This defaults to a null string.

Output parameters:
  • privJWK - The private JSON Web Key that is created.
  • pubJWK - The public JSON Web key that is created.

Return value:
  • A status indicating if a JWK pair (or individual JWK for symmetric key algorithms) was successfully created for the given algorithm and (optionally) secret. If no JWK was created, this method will return an error describing why not.

Notes:
  • This method does not add a kid to the keys it creates. In order to use kids, they must be added after the keys are created. For example:
    Set sc=##class(%Net.JSON.JWK).Create("ES256",,.privJWK,.pubJWK)
If $$$ISOK(sc) {
	Set privJWK.kid=1
	Set pubJWK.kid=1
}
  • This method does not encrypt the keys it creates. In order to create encrypted JWKs, convert the JWKs created by this method into strings and then pass them through %Net.JSON.JWE:Encrypt() as the plaintext. For example:
    Set sc=##class(%Net.JSON.JWK).Create("ES256",,.privJWK,.pubJWK)
If $$$ISOK(sc) {
	Set privJWK=privJWK.%ToJSON()
	Set pubJWK=pubJWK.%ToJSON()
	Do ##class(%Net.JSON.JWE).Encrypt({"alg":"RSA1_5","enc":"A256CBC-HS512"},,,privJWK,,,JWKS,.encryptedPrivJWK)
	Do ##class(%Net.JSON.JWE).Encrypt({"alg":"RSA1_5","enc":"A256CBC-HS512"},,,pubJWK,,,JWKS,.encryptedPubJWK)
}

    Where JWKS is a JWKS that contains a key for RSA1_5.
  • This method will return an error if an unrecognized algorithm is used.
  • Assuming creation was successful, privJWK will always have a non-null value.
  • If the algorithm is symmetric, then pubJWK will be null even if creation succeeded.
classmethod CreateX509(alg As %String, x509 As %SYS.X509Credentials, Output privJWK As %DynamicObject, Output pubJWK As %DynamicObject) as %Status
This method creates a new JSON Web Key (JWK) pair for the given algorithm based on the RSA key(s) contained in the given %SYS.X509Credentials object.

Input parameters:
  • alg - The algorithm for which to create the JWK.
  • x509 - a %SYS.X509Credentials object containing the RSA keys to use. If this object contains a private key, then a public and private JWK will be returned. Otherwise, only the pubkc JWK will be returned.

Output parameters:
  • privJWK - The private JSON Web Key that is created.
  • pubJWK - The public JSON Web key that is created.

Return value:
  • A status indicating if a JWK pair (or just a public JWK) was successfully created for the given algorithm. If no JWK was created, this method will return an error describing why not.

Notes:
  • This method does not add a kid to the keys it creates. In order to use kids, they must be added after the keys are created. For example:
    Set sc=##class(%Net.JSON.JWK).CreateX509("RS256",x509,.privJWK,.pubJWK)
If $$$ISOK(sc) {
	Set privJWK.kid=1
	Set pubJWK.kid=1
}
  • This method does not encrypt the keys it creates. In order to create encrypted JWKs, convert the JWKs created by this method into strings and then pass them through %Net.JSON.JWE:Encrypt() as the plaintext. For example:
    Set sc=##class(%Net.JSON.JWK).CreateX509("RS256",x509,.privJWK,.pubJWK)
If $$$ISOK(sc) {
	Set privJWK=privJWK.%ToJSON()
	Set pubJWK=pubJWK.%ToJSON()
	Do ##class(%Net.JSON.JWE).Encrypt({"alg":"RSA1_5","enc":"A256CBC-HS512"},,,privJWK,,,JWKS,.encryptedPrivJWK)
	Do ##class(%Net.JSON.JWE).Encrypt({"alg":"RSA1_5","enc":"A256CBC-HS512"},,,pubJWK,,,JWKS,.encryptedPubJWK)
}

    Where JWKS is a JWKS that contains a key for RSA1_5.
  • This method will return an error if an unrecognized algorithm is used.
  • Assuming creation was successful, pubJWK will always have a non-null value.
classmethod JWKtoASN1(JWK As %DynamicObject, Output ASN1 As %String) as %Status
This method converts a key in JSON Web Key (JWK) format to PEM-encoded DER ASN.1 format.

Input parameters:
  • JWK - JSON Web Key representation of a private or public key.

Output parameters:
  • ASN1 - PEM-encoded DER ASN.1 representation of the private or public key.

Return value:
  • A status indicating whether or not the JWK was successfully converted to ASN.1 format, where error values indicate that the conversion failed and describe the reason why.

Notes:
  • Currently this method only supports RSA and elliptic curve keys.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab