IPWorks Encrypt 2020 Node.js Edition

Questions / Feedback?

Sign Method

Signs the payload with the specified algorithm.

Syntax

jws.sign([callback])

Callback

The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).

The callback for this method is defined as:

function(err){ }

'err' is the error that occurred. If there was no error, then 'err' is 'null'.

'err' has 2 properties which hold detailed information:

err.code
err.message

Remarks

This method signs the input with the specified Algorithm.

Before calling the Sign method set Algorithm to the algorithm which will be used to sign the message. The result of signing is a compact serialized JWS string. For instance:

eyJhbGciOiJIUzI1NiJ9.dGVzdA.o_JihJlCwvBO1AgY_Ao3_VBivdFmj3ufv3ZWAqYF4Ow

The class is agnostic of the payload that is signed. Any value may be signed. KeyId may be set to include an identifier to help the receiving party identify the key used to sign the message. The following properties are applicable when calling this method:

  • Algorithm (required)
  • Certificate (conditional - required for ECDSA and RSA)
  • Key (conditional - required for HMAC)
  • HeaderParams
  • KeyId
  • Overwrite

Input and Output Properties

The class will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

Notes for HMAC Algorithms (HS256, HS384, HS512)

When Algorithm is set to a HMAC algorithm Key must be set to a key of appropriate length for the algorithm. The Key should be the same number of bits as the algorithm being used. For instance a 256 bit key would be used for HS256.

The example code below uses the EzRand class to generate a key, but the key may be created using any means. The key must be known by both parties in order for signing and verification to take place.


//Generate a 256 bit (32 byte) key
Ezrand ezrand = new Ezrand();
ezrand.RandBytesLength = 32;
ezrand.GetNextBytes();
byte[] key = ezrand.RandBytesB;

//Sign the payload using HS256
Jws jws = new Jws();
jws.Algorithm = JwsAlgorithms.jwsHS256;
jws.InputMessage = "test data";
jws.KeyB = key;
jws.Sign();

string signedData = jws.OutputMessage;

To use an existing HMAC key provide the bytes to the Key property. For instance:


//HMAC SHA-256 Key
byte[] key = new byte[] { 170, 171, 221, 209, 7, 181, 48, 178, 48, 118, 242, 132, 36, 218, 74, 140, 216, 165, 161, 70, 11, 42, 246, 205, 235, 231, 19, 48, 87, 141, 122, 10 };

//Sign the payload using HS256
Jws jws = new Jws();
jws.Algorithm = JwsAlgorithms.jwsHS256;
jws.InputMessage = "test data";
jws.KeyB = key;
jws.Sign();

string signedData = jws.OutputMessage;

Notes for RSA Algorithms (RS256, RS384, RS512, PS256, PS384, PS512)

The RSA based algorithms use asymmetric encryption. Signing is done with a private key and verification is done with a public key. The private key may be in PFX or PEM format.


Jws jws = new Jws();
jws.Algorithm = JwsAlgorithms.jwsRS256;
jws.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "..\\jwt.pfx", "test", "*");
jws.InputMessage = "test";
jws.Sign();

string signedMessage = jws.OutputMessage;

Notes for ECDSA Algorithms (ES256, ES384, ES512)

ECDSA algorithms require a valid ECC private key to sign. The ECC class can be used to create or import an ECC key into the Certificate format accepted by the JWS class.


//Create an ECC key with SHA-256
Ecc ecc = new Ecc();
ecc.HashAlgorithm = EccHashAlgorithms.ehaSHA256;
ecc.CreateKey();

string privKey = ecc.Key.PrivateKey;

//Sign the payload using ES256
Jws jws = new Jws();
jws.Algorithm = JwsAlgorithms.jwsES256;
jws.Certificate = new Certificate(CertStoreTypes.cstPEMKeyBlob, privKey, "", "*");
jws.InputMessage = "test";
jws.Sign();

string signedMessage = jws.OutputMessage;

To use an existing ECC Key populate the Rx, Ry, and K values of Key property in the ECC class first. For instance:


//Import an existing ECC private key
Ecc ecc = new Ecc();

byte[] x_bytes = new byte[] { 171, 170, 196, 151, 94, 196, 231, 12, 128, 232, 17, 61, 45, 105, 41, 209, 192, 187, 112, 242, 110, 178, 95, 240, 36, 55, 83, 171, 190, 176, 78, 13 };
byte[] y_bytes = new byte[] { 197, 75, 134, 245, 245, 28, 199, 9, 7, 117, 1, 54, 49, 178, 135, 252, 62, 89, 35, 180, 117, 80, 231, 23, 110, 250, 28, 124, 219, 253, 224, 156 };
byte[] k_bytes = new byte[] { 81, 65, 201, 24, 235, 249, 162, 148, 169, 150, 109, 181, 61, 238, 145, 122, 31, 30, 151, 94, 239, 90, 222, 217, 63, 103, 54, 2, 176, 232, 248, 168 };

ecc.Key.RxB = x_bytes;
ecc.Key.RyB = y_bytes;
ecc.Key.KB = k_bytes;

string privKey = ecc.Key.PrivateKey;

//Sign the payload using ES256
Jws jws = new Jws();
jws.Algorithm = JwsAlgorithms.jwsES256;
jws.Certificate = new Certificate(CertStoreTypes.cstPEMKeyBlob, privKey, "", "*");
jws.InputMessage = "test";
jws.Sign();

string signedMessage = jws.OutputMessage;

Notes for Unsecured (none)

To create a JWS token without any security set Algorithm to jwsNone.


Jws jws = new Jws();
jws.Algorithm = JwsAlgorithms.jwsNone;
jws.InputMessage = "test";
jws.Sign();

string unsecuredMessage = jws.OutputMessage;

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Encrypt 2020 Node.js Edition - Version 20.0 [Build 8155]