Encrypt Method

Encrypts the payload with the specified algorithms.

procedure Encrypt();

Remarks

This method encrypts the input data using the specified algorithms.

JSON Web Encryption (JWE) is performed by first generating a random key used to encrypt the content. The content encryption key is used to encrypt the content using the algorithm specified by ContentEncryptionAlgorithm. The content encryption key is then encrypted itself using the algorithm specified by EncryptionAlgorithm. The content encryption key is not directly exposed in the API as it is randomly generated.

After calling this method the compact serialized JWE string is written to the specified output location. For instance:

eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiaXYiOiJMa0tNeTZ5Qlpfbzh6QW92IiwidGFnIjoiSmpMTkRsV3l3bWt3V2pMa0NLU0xxQSJ9.wiwySYm6fXZre-3IdT1tb_02KMQDrMICwUawVf7Gjhc.k84s7ne8J41QnA5BQ31k_A.kjIveRjjNYV4x92CVE9Agw.uAygkyeO2KWeFQIy9JLU0A

The component is agnostic of the payload that is encrypted. Any value may be encrypted. KeyId may be set to include an identifier to help the receiving party identify the key or certificate used to encrypt the data. The following properties are applicable when calling this method:

EncryptionAlgorithm (required)
Key (conditional - required for AES)
KeyPassword (conditional - required for PBES)
Certificate (conditional - required for ECDH and RSA)
ContentEncryptionAlgorithm
CompressionAlgorithm
Header*
Overwrite

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:

SetOutputStream
OutputFile
OutputMessage: The output data is written to this property if no other destination is specified.

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

Notes for AES Algorithms (A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW)

When EncryptionAlgorithm is set to a AES algorithm Key must be set to a key of appropriate length for the algorithm. For instance a 256 bit key would be used for A256KW.

The example below uses the EzRand component to generate a key, but the key may be created using any method. The key must be known by both parties in order for encryption and decryption to take place.

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

//Encrypt the payload using A256KW
Jwe jwe = new Jwe();
jwe.KeyB = key;
jwe.InputMessage = "test data";
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaA256KW;
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

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

byte[] key = new byte[] { 164, 60, 194, 0, 161, 189, 41, 38, 130, 89, 141, 164, 45, 170, 159, 209, 69, 137, 243, 216, 191, 131, 47, 250, 32, 107, 231, 117, 37, 158, 225, 234 };

//Encrypt the payload using A256KW
Jwe jwe = new Jwe();
jwe.KeyB = key;
jwe.InputMessage = "test data";
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaA256KW;
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

Notes for RSA Algorithms (RSA1_5, RSA-OEAP, RSA-OAEP-256)

The RSA based algorithms use asymmetric encryption. Encrypting is done with a public key and decryption is done with a private key. The public certificate should be in PEM (base64) format. For instance:

Jwe jwe = new Jwe();
jwe.Certificate = new Certificate("..\\recipient.cer");
jwe.InputMessage = "test data";
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaRSA_OAEP;
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

Notes for ECDH Algorithms (ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW)

ECDH algorithms require a valid ECC public key to encrypt the message. If the key was originally created with the ECC component the PEM encoded PublicKey may be used directly with the Certificate property. An example PEM encoded public certificate created by the ECC component:

-----BEGIN PUBLIC KEY----- MIIBMjCB7AYHKoZIzj0CATCB4AIBATAsBgcqhkjOPQEBAiEA/////wAAAAEAAAAAAAAAAAAA AAD///////////////8wRAQg/////wAAAAEAAAAAAAAAAAAAAAD///////////////wEIFrG NdiqOpPns+u9VXaYhrxlHQawzFOw9jvOPD4n0mBLBEEEaxfR8uEsQkf4vOblY6RA8ncDfYEt 6zOg9KE5RdiYwpZP40Li/hp/m47n60p8D54WK84zV2sxXs7LtkBoN79R9QIhAP////8AAAAA //////////+85vqtpxeehPO5ysL8YyVRAgEBA0EEIC5rbLp11Mnz6cBXLLriaDIov3rm8RAY x/OR0bOKiff0cQy+sLVaxjseqFk/+Xvl4ORSv5Z6HdHv5GyEpA0UoA== -----END PUBLIC KEY-----

Jwe jwe = new Jwe();
jwe.Certificate = new Certificate(CertStoreTypes.cstPublicKeyFile, pubKeyFile, "", "*");
jwe.InputMessage = "test data";
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaECDH_ES_A256KW;
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

To use an ECC public key created by other means the ECC component may be used to import the key parameters. Populate the Rx and Ry properties of the ECC component first to obtain the PEM formatted public key. For instance:

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 };

Ecc ecc = new Ecc();
ecc.Key.RxB = x_bytes;
ecc.Key.RyB = y_bytes;

string pubKey = ecc.Key.PublicKey;

Jwe jwe = new Jwe();
jwe.Certificate = new Certificate(CertStoreTypes.cstPublicKeyFile, pubKey, "", "*");
jwe.InputMessage = "test data";
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaECDH_ES_A256KW;
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

Notes for PBES Algorithms (PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW

PBES algorithms derive a content encryption key from the KeyPassword property. Set KeyPassword to a shared secret.

Jwe jwe = new Jwe();
jwe.KeyPassword = "secret";
jwe.InputMessage = "test data";
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaPBES2_HS512_A256KW;
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

Notes for Direct Shared Keys

When EncryptionAlgorithm is set to Direct the Key property must be set to a valid symmetric key that will be used directly by the ContentEncryptionAlgorithm. In this case a content encryption key is not generated randomly, the Key is used instead. The length of the specified Key must be valid for the selected ContentEncryptionAlgorithm. For instance:

//Generate a 256 bit (32 byte) key
Ezrand rand = new Ezrand();
rand.RandBytesLength = 32;
rand.GetNextBytes();

byte[] key = rand.RandBytesB;

Jwe jwe = new Jwe();
jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaDir;
jwe.ContentEncryptionAlgorithm = JweContentEncryptionAlgorithms.ceaA256GCM;
jwe.KeyB = key;
jwe.InputMessage = "test data";
jwe.Encrypt();

string encryptedData = jwe.OutputMessage;

IPWorks Encrypt 2020 Delphi Edition Website Download Support Questions / Feedback?
	Encrypt Method Encrypts the payload with the specified algorithms. procedure Encrypt(); Remarks This method encrypts the input data using the specified algorithms. JSON Web Encryption (JWE) is performed by first generating a random key used to encrypt the content. The content encryption key is used to encrypt the content using the algorithm specified by ContentEncryptionAlgorithm. The content encryption key is then encrypted itself using the algorithm specified by EncryptionAlgorithm. The content encryption key is not directly exposed in the API as it is randomly generated. After calling this method the compact serialized JWE string is written to the specified output location. For instance: `eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiaXYiOiJMa0tNeTZ5Qlpfbzh6QW92IiwidGFnIjoiSmpMTkRsV3l3bWt3V2pMa0NLU0xxQSJ9.wiwySYm6fXZre-3IdT1tb_02KMQDrMICwUawVf7Gjhc.k84s7ne8J41QnA5BQ31k_A.kjIveRjjNYV4x92CVE9Agw.uAygkyeO2KWeFQIy9JLU0A` The component is agnostic of the payload that is encrypted. Any value may be encrypted. KeyId may be set to include an identifier to help the receiving party identify the key or certificate used to encrypt the data. The following properties are applicable when calling this method: EncryptionAlgorithm (required) Key (conditional - required for AES) KeyPassword (conditional - required for PBES) Certificate (conditional - required for ECDH and RSA) ContentEncryptionAlgorithm CompressionAlgorithm Header* Overwrite 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: SetInputStream InputFile InputMessage When a valid source is found the search stops. The order in which the output properties are checked is as follows: SetOutputStream OutputFile OutputMessage: The output data is written to this property if no other destination is specified. When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing. Notes for AES Algorithms (A128KW, A192KW, A256KW, A128GCMKW, A192GCMKW, A256GCMKW) When EncryptionAlgorithm is set to a AES algorithm Key must be set to a key of appropriate length for the algorithm. For instance a 256 bit key would be used for A256KW. The example below uses the EzRand component to generate a key, but the key may be created using any method. The key must be known by both parties in order for encryption and decryption to take place. //Generate a 256 bit (32 byte) key Ezrand rand = new Ezrand(); rand.RandBytesLength = 32; rand.GetNextBytes(); byte[] key = rand.RandBytesB; //Encrypt the payload using A256KW Jwe jwe = new Jwe(); jwe.KeyB = key; jwe.InputMessage = "test data"; jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaA256KW; jwe.Encrypt(); string encryptedData = jwe.OutputMessage; To use an existing AES key provide the bytes to the Key property. For instance: byte[] key = new byte[] { 164, 60, 194, 0, 161, 189, 41, 38, 130, 89, 141, 164, 45, 170, 159, 209, 69, 137, 243, 216, 191, 131, 47, 250, 32, 107, 231, 117, 37, 158, 225, 234 }; //Encrypt the payload using A256KW Jwe jwe = new Jwe(); jwe.KeyB = key; jwe.InputMessage = "test data"; jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaA256KW; jwe.Encrypt(); string encryptedData = jwe.OutputMessage; Notes for RSA Algorithms (RSA1_5, RSA-OEAP, RSA-OAEP-256) The RSA based algorithms use asymmetric encryption. Encrypting is done with a public key and decryption is done with a private key. The public certificate should be in PEM (base64) format. For instance: Jwe jwe = new Jwe(); jwe.Certificate = new Certificate("..\\recipient.cer"); jwe.InputMessage = "test data"; jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaRSA_OAEP; jwe.Encrypt(); string encryptedData = jwe.OutputMessage; Notes for ECDH Algorithms (ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW) ECDH algorithms require a valid ECC public key to encrypt the message. If the key was originally created with the ECC component the PEM encoded `PublicKey` may be used directly with the Certificate property. An example PEM encoded public certificate created by the ECC component: `-----BEGIN PUBLIC KEY----- MIIBMjCB7AYHKoZIzj0CATCB4AIBATAsBgcqhkjOPQEBAiEA/////wAAAAEAAAAAAAAAAAAA AAD///////////////8wRAQg/////wAAAAEAAAAAAAAAAAAAAAD///////////////wEIFrG NdiqOpPns+u9VXaYhrxlHQawzFOw9jvOPD4n0mBLBEEEaxfR8uEsQkf4vOblY6RA8ncDfYEt 6zOg9KE5RdiYwpZP40Li/hp/m47n60p8D54WK84zV2sxXs7LtkBoN79R9QIhAP////8AAAAA //////////+85vqtpxeehPO5ysL8YyVRAgEBA0EEIC5rbLp11Mnz6cBXLLriaDIov3rm8RAY x/OR0bOKiff0cQy+sLVaxjseqFk/+Xvl4ORSv5Z6HdHv5GyEpA0UoA== -----END PUBLIC KEY-----` Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPublicKeyFile, pubKeyFile, "", ""); jwe.InputMessage = "test data"; jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaECDH_ES_A256KW; jwe.Encrypt(); string encryptedData = jwe.OutputMessage; To use an ECC public key created by other means the ECC component may be used to import the key parameters. Populate the `Rx` and `Ry` properties of the ECC component first to obtain the PEM formatted public key. For instance: 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 }; Ecc ecc = new Ecc(); ecc.Key.RxB = x_bytes; ecc.Key.RyB = y_bytes; string pubKey = ecc.Key.PublicKey; Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPublicKeyFile, pubKey, "", ""); jwe.InputMessage = "test data"; jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaECDH_ES_A256KW; jwe.Encrypt(); string encryptedData = jwe.OutputMessage; Notes for PBES Algorithms (PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW PBES algorithms derive a content encryption key from the KeyPassword property. Set KeyPassword to a shared secret. Jwe jwe = new Jwe(); jwe.KeyPassword = "secret"; jwe.InputMessage = "test data"; jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaPBES2_HS512_A256KW; jwe.Encrypt(); string encryptedData = jwe.OutputMessage; Notes for Direct Shared Keys When EncryptionAlgorithm is set to `Direct` the Key property must be set to a valid symmetric key that will be used directly by the ContentEncryptionAlgorithm. In this case a content encryption key is not generated randomly, the Key is used instead. The length of the specified Key must be valid for the selected ContentEncryptionAlgorithm. For instance: //Generate a 256 bit (32 byte) key Ezrand rand = new Ezrand(); rand.RandBytesLength = 32; rand.GetNextBytes(); byte[] key = rand.RandBytesB; Jwe jwe = new Jwe(); jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaDir; jwe.ContentEncryptionAlgorithm = JweContentEncryptionAlgorithms.ceaA256GCM; jwe.KeyB = key; jwe.InputMessage = "test data"; jwe.Encrypt(); string encryptedData = jwe.OutputMessage;
Copyright (c) 2022 /n software inc. - All rights reserved. IPWorks Encrypt 2020 Delphi Edition - Version 20.0 [Build 8155]

IPWorks Encrypt 2020 Delphi Edition

Encrypt Method

Remarks