Skip to main content

%Net.JSON.JWS

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

This class provides methods to sign and validate JSON Web Signatures, as defined in RFC 7515.

Method Inventory

Methods

classmethod Sign(protectedHeader As %DynamicObject, unprotectedHeader As %DynamicObject, payload As %String, serialization As %String = "compact", JWKS As %String = "", Output JWS As %String) as %Status
This method signs a header and payload to make a JWS.

Input parameters:
  • protectedHeader - The JOSE Protected Header to use.
  • unprotectedHeader - The JOSE Unprotected Header to use.
  • payload - The message being signed.
  • serialization - The JWS Serialization format to use. Accepted serialization formats are "compact" and "json". The format type determines the structure of the JWS that is created. This defaults to "compact"
  • JWKS - The JSON Web Key Set that contains the key that will be used to sign this JWS. This defaults to the null string.

Output parameters:
  • JWS - The JSON Web Signature that is created. If json serialization is used, this will be a valid JSON string. If compact serialization is used it will be a non-JSON string.

Return value:
  • A status indicating whether or not a JWS was created from the inputs. If this method is unable to create a JWS from the inputs it will return an error indicating why this is.

Notes:
  • This method will fail if provided an empty payload.
  • If none of the provided headers contains a kid but in the process of creating the JWS a JWK with a kid is used, that kid will be added to the protected header before the JWS is created.
  • If the "compact" serialization format is used, the protected header MUST be present and the unprotected header MUST be absent. If the "json" format is used, at least one of the protected header and unprotected header MUST be present and they both CAN be present.
  • Only the JWS Compact Serialization and the flattened syntax of the JWS JSON Serialization are supported for signing (not the general format of the JWS JSON Serialization).
  • Using the default JWKS (which is null) will result in an error in all cases except for when the algorithm "none" is used.
classmethod Validate(JWS As %String, JWKS As %String = "", acceptUnsecured As %Boolean = 0, Output validations As %DynamicArray) as %Boolean
This method validates a JWS.

Input parameters:
  • JWS - The JSON Web Signature to be validated.
  • JWKS - The JSON Web Key Set that contains the key that will be used to validate this JWS. This defaults to the null string.
  • acceptUnsecured - A boolean value indicating whether or not to accept JWSs that use the algorithm "none". This defaults to false.

Output parameters:
  • validations - A dynamic array containing information about the validity of the signatures in the JWS. The validations array contains one DynamicObject for each signature in the JWS, each containing the following fields:
    • "signature": The signature this DynamicObject contains information about.
    • "valid": A boolean indicating whether or not the signature is valid.
    • "error": A string containing any error message that was generating during the checking of the signature.
  • Return value:
    • A boolean indicator of whether or not validation succeeded. If the JWS contains multiple signatures, this method will return true as long as at least one of the signatures is valid.

    Notes:
    • This method will not accept an empty JWS. If provided one, it will return false and the validations array will be null.
    • This method supports validation for the JWS Compact Serialization and both the flattened and general syntax of the JWS JSON Serialization.
    • Using the default JWKS (which is null) will result in an error in all cases except for when the algorithm "none" was used (and unsecured JWSs are accepted).
    • Some applications may only want to consider a JWS with multiple signatures valid if all of the signatures are valid. Since this method only needs one signature to be valid in order to return true, applications that require all signatures to be valid should use the error field of each signature in the validations array to meet their needs. Specifically, they should check to see if any signature's error field is not null. Any signature whose error field is not null failed to validate (which is why it has an error message), so the presence of any non-null error fields means that at least one signature failed to validate.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab