IPWorks Encrypt 2020 Delphi Edition

Questions / Feedback?

Sign Method

Signs the payload with the specified algorithm.

procedure Sign();

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 component 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:

Input and Output Properties

The component 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:

When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.

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 component 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 component can be used to create or import an ECC key into the Certificate format accepted by the JWS component.


//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 component 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 Delphi Edition - Version 20.0 [Build 8155]