JWE Component

Properties   Methods   Events   Config Settings   Errors  

Create, Encrypt and Decrypt JSON Web Encryption (JWE) messages.

Syntax

nsoftware.IPWorksEncrypt.Jwe

Remarks

The JWE component supports encrypting and decrypting JSON Web Encryption (JWE) messages.

Specify any payload via input properties and use Encrypt to create a JWE message using a variety of algorithms including ECDH, RSA, and AES. Use Decrypt to decrypt the payload of any received JWE message. The following algorithms are supported:

• RSA1_5
• RSA-OAEP
• RSA-OAEP-256
• A128KW
• A192KW
• A256KW
• dir
• ECDH-ES
• ECDH-ES+A128KW
• ECDH-ES+A192KW
• ECDH-ES+A256KW
• A128GCMKW
• A192GCMKW
• A256GCMKW
• PBES2-HS256+A128KW
• PBES2-HS384+A192KW
• PBES2-HS512+A256KW

See EncryptionAlgorithm for more details about supported algorithms.

Encrypting

The Encrypt method may be used to encrypt a payload with a variety of 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
• HeaderParams
• 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;

Decrypting

The Decrypt method may be used to decrypt a received JWE message. Before calling the Decrypt method set InputMessage or InputFile to a valid compact serialized JWE string. For instance:

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

The type and format of the private key depends on the algorithm used to encrypt the data. The following table summarizes the relationship:

If this method returns without error decryption was successful. If decryption fails then this method throws an exception. After calling this method the payload will be present in the OutputMessage or file specified by OutputFile and the HeaderParams property will contain the headers. Headers of the parsed message are also available through the HeaderParam event.

The following properties are applicable when calling this method:

• Certificate (conditional - required for RSA and ECDH)
• Key (conditional - required for AES)
• ContentEncryptionAlgorithm (only if StrictValidation is True)
• EncryptionAlgorithm (only if StrictValidation is True)
• HeaderParams
• Overwrite
• StrictValidation

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)

To decrypt messages that use AES encryption 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 key must be known by both parties in order for encryption and decryption to take place.

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 }; Jwe jwe = new Jwe(); jwe.KeyB = key; jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = 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 certificate with private key must be specified. For instance:

Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "..\\jwt.pfx", "password", "*"); jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

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

ECDH algorithms require a valid ECC private key to decrypt the message. If the key was originally created with the ECC component the PEM encoded PrivateKey may be used directly with the Certificate property.

Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPEMKeyFile, privKeyFile, "", "*"); jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

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

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; Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPEMKeyBlob, privKey, "", "*"); jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = 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 the shared secret.

Jwe jwe = new Jwe(); jwe.KeyPassword = "secret"; jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

Notes for Direct Shared Keys

When Direct encryption is used the Key property must be set to a valid symmetric key that will be used directly by the ContentEncryptionAlgorithm. 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 }; Jwe jwe = new Jwe(); jwe.KeyB = key; jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

Other Functionality

In addition to standard encrypting and decrypting the component also supports a variety of other features including:

• Adding custom header parameters with AddHeaderParam
• Enforcing algorithm restrictions when decrypting by setting StrictValidation
• Inspect the JWE headers without decrypting by calling Parse

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Certificate Property (JWE Component)

The certificate used for encryption or decryption.

Syntax

• C#
• VB.NET

public Certificate Certificate { get; set; }

Public Property Certificate As Certificate

Remarks

This property specifies a certificate for encryption or decryption.

When calling Encrypt and EncryptionAlgorithm is set to an RSA or ECDH algorithm this property must be set to a public certificate of the recipient.

When calling Decrypt and the message was encrypted using an RSA or ECDH EncryptionAlgorithm this property specifies the certificate with private key used to decrypt the message.

ContentEncryptionAlgorithm Property (JWE Component)

The algorithm used to encrypt the content.

Syntax

• C#
• VB.NET

public JweContentEncryptionAlgorithms ContentEncryptionAlgorithm { get; set; }

enum JweContentEncryptionAlgorithms {
  ceaA128CBC_HS256,
  ceaA192CBC_HS384,
  ceaA256CBC_HS512,
  ceaA128GCM,
  ceaA192GCM,
  ceaA256GCM
}

Public Property ContentEncryptionAlgorithm As JweContentEncryptionAlgorithms

Enum JweContentEncryptionAlgorithms
  ceaA128CBC_HS256
  ceaA192CBC_HS384
  ceaA256CBC_HS512
  ceaA128GCM
  ceaA192GCM
  ceaA256GCM
End Enum

Default Value

0

Remarks

This property specifies the algorithm used to encrypt the content.

The following values are supported.

EncryptionAlgorithm Property (JWE Component)

The key encryption algorithm.

Syntax

• C#
• VB.NET

public JweEncryptionAlgorithms EncryptionAlgorithm { get; set; }

enum JweEncryptionAlgorithms {
  eaRSA1_5,
  eaRSA_OAEP,
  eaRSA_OAEP_256,
  eaA128KW,
  eaA192KW,
  eaA256KW,
  eaDir,
  eaECDH_ES,
  eaECDH_ES_A128KW,
  eaECDH_ES_A192KW,
  eaECDH_ES_A256KW,
  eaA128GCMKW,
  eaA192GCMKW,
  eaA256GCMKW,
  eaPBES2_HS256_A128KW,
  eaPBES2_HS384_A192KW,
  eaPBES2_HS512_A256KW
}

Public Property EncryptionAlgorithm As JweEncryptionAlgorithms

Enum JweEncryptionAlgorithms
  eaRSA1_5
  eaRSA_OAEP
  eaRSA_OAEP_256
  eaA128KW
  eaA192KW
  eaA256KW
  eaDir
  eaECDH_ES
  eaECDH_ES_A128KW
  eaECDH_ES_A192KW
  eaECDH_ES_A256KW
  eaA128GCMKW
  eaA192GCMKW
  eaA256GCMKW
  eaPBES2_HS256_A128KW
  eaPBES2_HS384_A192KW
  eaPBES2_HS512_A256KW
End Enum

Default Value

0

Remarks

This property specifies the algorithm used to encrypt the randomly generated content encryption key.

When using an AES algorithm Key must be specified. When using an RSA or ECDH algorithm Certificate must be specified. When using a PBES algorithm KeyPassword must be specified;. Possible values are:

When set to an ECDH algorithm the following settings are also applicable:

• PartyUInfo
• PartyVInfo

When set to a PBES algorithm the following settings are also applicable:

• PBES2Count
• PBES2SaltLength

HeaderParams Property (JWE Component)

The JOSE header parameters.

Syntax

• C#
• VB.NET

public HeaderParamList HeaderParams { get; }

Public Property HeaderParams As HeaderParamList

Remarks

This property specifies the JOSE header parameters. This may be populated before calling Sign or Encrypt. This is populated with the parsed header values after calling Verify, Decrypt, or Parse.

This property is not available at design time.

InputFile Property (JWE Component)

The file to process.

Syntax

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

This property specifies the file to be processed. Set this property to the full or relative path to the file which will be processed.

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.

InputMessage Property (JWE Component)

The message to process.

Syntax

• C#
• VB.NET

public string InputMessage { get; set; }
public byte[] InputMessageB { get; set; }

Public Property InputMessage As String
Public Property InputMessageB As Byte()

Default Value

""

Remarks

This property specifies the message to be processed.

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.

Key Property (JWE Component)

The secret key for the AES algorithm.

Syntax

• C#
• VB.NET

public string Key { get; set; }
public byte[] KeyB { get; set; }

Public Property Key As String
Public Property KeyB As Byte()

Default Value

""

Remarks

This property specifies the key used for AES encryption and decryption.

When EncryptionAlgorithm is set to an AES algorithm this property must hold the symmetric key used for encryption and decryption. The size of the key must match the size of the algorithm. For instance when selecting the algorithm A256GCMKW (AES 256) the size of the key must also be 256 bits (32 bytes).

In the case where EncryptionAlgorithm is set to Direct this key is used directly with the algorithm specified by ContentEncryptionAlgorithm and must be an appropriate size for the selected ContentEncryptionAlgorithm.

KeyId Property (JWE Component)

The Id of the key used to encrypt the message.

Syntax

• C#
• VB.NET

public string KeyId { get; set; }

Public Property KeyId As String

Default Value

""

Remarks

This property optionally specifies the Id of the key used to encrypt the message.

Any string value may be supplied here to help the other party identify the key used to encrypt the message. This may be set before calling the Encrypt method.

KeyPassword Property (JWE Component)

The key password used in the PBES algorithm.

Syntax

• C#
• VB.NET

public string KeyPassword { get; set; }

Public Property KeyPassword As String

Default Value

""

Remarks

This property specifies the key password used to derive a key when using a PBES EncryptionAlgorithm.

This is only applicable to PBES algorithms and must be set before calling Encrypt or Decrypt.

OutputFile Property (JWE Component)

The output file when encrypting or decrypting.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

This property specifies the file to which the output will be written when Encrypt or Decrypt is called. This may be set to an absolute or relative path.

This property is only applicable to Encrypt and Decrypt.

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.

OutputMessage Property (JWE Component)

The output message after processing.

Syntax

• C#
• VB.NET

public string OutputMessage { get; }
public byte[] OutputMessageB { get; }

Public ReadOnly Property OutputMessage As String
Public ReadOnly Property OutputMessageB As Byte()

Default Value

""

Remarks

This property will be populated with the output from the operation if OutputFile and SetOutputStream are not set.

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.

This property is read-only and not available at design time.

Overwrite Property (JWE Component)

Indicates whether or not the component should overwrite files.

Syntax

• C#
• VB.NET

public bool Overwrite { get; set; }

Public Property Overwrite As Boolean

Default Value

False

Remarks

This property indicates whether or not the component will overwrite OutputFile. If Overwrite is False, an error will be thrown whenever OutputFile exists before an operation. The default value is False.

AddHeaderParam Method (JWE Component)

Adds additional header parameters.

Syntax

• C#
• VB.NET

public void AddHeaderParam(string name, string value, int dataType);

Async Version
public async Task AddHeaderParam(string name, string value, int dataType);
public async Task AddHeaderParam(string name, string value, int dataType, CancellationToken cancellationToken);

Public Sub AddHeaderParam(ByVal name As String, ByVal value As String, ByVal dataType As Integer)

Async Version
Public Sub AddHeaderParam(ByVal name As String, ByVal value As String, ByVal dataType As Integer) As Task
Public Sub AddHeaderParam(ByVal name As String, ByVal value As String, ByVal dataType As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add additional header parameters before calling Encrypt.

The Name and Value parameters define the name and value of the parameter respectively. The DataType parameter specifies the JSON data type of the value. Possible values for DataType are:

• 0 (Object)
• 1 (Array)
• 2 (String)
• 3 (Number)
• 4 (Bool)
• 5 (Null)

{
	"alg": "A256GCMKW",
	"crit": [
		"exp"
	],
	"enc": "A128CBC-HS256",
	"exp": 12345687,
	"iv": "SFZ9o0KKN8qF8yod",
	"tag": "tREHGKuViLo7s3QpRTulkg",
	"type": "JWT"
}

The following code can be used:

Jwe jwe = new Jwe(); jwe.EncryptionAlgorithm = JweEncryptionAlgorithms.eaA256GCMKW; jwe.KeyB = key; jwe.AddHeaderParam("type", "JWT", 2); jwe.AddHeaderParam("crit", "[\"exp\"]", 1); jwe.AddHeaderParam("exp", "12345687", 3); jwe.InputMessage = "test"; jwe.Encrypt(); string encryptedData = jwe.OutputMessage;

Note: When calling Encrypt the component will automatically add headers based on the selected EncryptionAlgorithm and other properties that may be set.

Parameters Automatically Set:

Config Method (JWE Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Decrypt Method (JWE Component)

Decrypts the payload.

Syntax

• C#
• VB.NET

public void Decrypt();

Async Version
public async Task Decrypt();
public async Task Decrypt(CancellationToken cancellationToken);

Public Sub Decrypt()

Async Version
Public Sub Decrypt() As Task
Public Sub Decrypt(cancellationToken As CancellationToken) As Task

Remarks

This method decrypts the input data.

Before calling the Decrypt method set InputMessage or InputFile to a valid compact serialized JWE string. For instance:

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

The type and format of the private key depends on the algorithm used to encrypt the data. The following table summarizes the relationship:

If this method returns without error decryption was successful. If decryption fails then this method throws an exception. After calling this method the payload will be present in the OutputMessage or file specified by OutputFile and the HeaderParams property will contain the headers. Headers of the parsed message are also available through the HeaderParam event.

The following properties are applicable when calling this method:

• Certificate (conditional - required for RSA and ECDH)
• Key (conditional - required for AES)
• ContentEncryptionAlgorithm (only if StrictValidation is True)
• EncryptionAlgorithm (only if StrictValidation is True)
• HeaderParams
• Overwrite
• StrictValidation

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)

To decrypt messages that use AES encryption 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 key must be known by both parties in order for encryption and decryption to take place.

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 }; Jwe jwe = new Jwe(); jwe.KeyB = key; jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = 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 certificate with private key must be specified. For instance:

Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "..\\jwt.pfx", "password", "*"); jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

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

ECDH algorithms require a valid ECC private key to decrypt the message. If the key was originally created with the ECC component the PEM encoded PrivateKey may be used directly with the Certificate property.

Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPEMKeyFile, privKeyFile, "", "*"); jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

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

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; Jwe jwe = new Jwe(); jwe.Certificate = new Certificate(CertStoreTypes.cstPEMKeyBlob, privKey, "", "*"); jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = 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 the shared secret.

Jwe jwe = new Jwe(); jwe.KeyPassword = "secret"; jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

Notes for Direct Shared Keys

When Direct encryption is used the Key property must be set to a valid symmetric key that will be used directly by the ContentEncryptionAlgorithm. 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 }; Jwe jwe = new Jwe(); jwe.KeyB = key; jwe.InputMessage = encryptedData; jwe.Decrypt(); string decryptedData = jwe.OutputMessage;

Encrypt Method (JWE Component)

Encrypts the payload with the specified algorithms.

Syntax

• C#
• VB.NET

public void Encrypt();

Async Version
public async Task Encrypt();
public async Task Encrypt(CancellationToken cancellationToken);

Public Sub Encrypt()

Async Version
Public Sub Encrypt() As Task
Public Sub Encrypt(cancellationToken As CancellationToken) As Task

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
• HeaderParams
• 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;

Parse Method (JWE Component)

Parses the compact serialized JWE string.

Syntax

• C#
• VB.NET

public void Parse();

Async Version
public async Task Parse();
public async Task Parse(CancellationToken cancellationToken);

Public Sub Parse()

Async Version
Public Sub Parse() As Task
Public Sub Parse(cancellationToken As CancellationToken) As Task

Remarks

This method parses, but does not decrypt, the JWE string.

Take care when using this method as no decryption is performed. This method may be helpful in cases where only header information is desired.

If decryption is desired, use Decrypt instead. It is not necessary to call this method before calling Decrypt. Decrypt will both parse and decrypt the message.

When calling this method the headers are parsed. The HeaderParam and RecipientInfo events will fire and the HeaderParams property will be populated.

Reset Method (JWE Component)

Resets the component

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

When called, the component will reset all of its properties to their default values.

SetInputStream Method (JWE Component)

Sets the stream from which the component will read data.

Syntax

• C#
• VB.NET

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method may be used to set a stream from which data will be read.

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.

SetOutputStream Method (JWE Component)

Sets the stream to which the component will write data.

Syntax

• C#
• VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method may be used to specify a stream to which data will be written.

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.

Error Event (JWE Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, JweErrorEventArgs e);

public class JweErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As JweErrorEventArgs)

Public Class JweErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

HeaderParam Event (JWE Component)

Fires once for each JOSE header parameter.

Syntax

• C#
• VB.NET

public event OnHeaderParamHandler OnHeaderParam;

public delegate void OnHeaderParamHandler(object sender, JweHeaderParamEventArgs e);

public class JweHeaderParamEventArgs : EventArgs {
  public string Name { get; }
  public string Value { get; }
  public int DataType { get; }
}

Public Event OnHeaderParam As OnHeaderParamHandler

Public Delegate Sub OnHeaderParamHandler(sender As Object, e As JweHeaderParamEventArgs)

Public Class JweHeaderParamEventArgs Inherits EventArgs
  Public ReadOnly Property Name As String
  Public ReadOnly Property Value As String
  Public ReadOnly Property DataType As Integer
End Class

Remarks

When Decrypt or Parse is called this event will fire once for each JOSE header parameter.

Name is the name of the parameter.

Value is the value of the parameter.

DataType specifies the JSON data type of the value. Possible values are:

• 0 (Object)
• 1 (Array)
• 2 (String)
• 3 (Number)
• 4 (Bool)
• 5 (Null)

RecipientInfo Event (JWE Component)

Fired with information about the recipient key of the encrypted message.

Syntax

• C#
• VB.NET

public event OnRecipientInfoHandler OnRecipientInfo;

public delegate void OnRecipientInfoHandler(object sender, JweRecipientInfoEventArgs e);

public class JweRecipientInfoEventArgs : EventArgs {
  public string KeyId { get; }
  public string Algorithm { get; }
}

Public Event OnRecipientInfo As OnRecipientInfoHandler

Public Delegate Sub OnRecipientInfoHandler(sender As Object, e As JweRecipientInfoEventArgs)

Public Class JweRecipientInfoEventArgs Inherits EventArgs
  Public ReadOnly Property KeyId As String
  Public ReadOnly Property Algorithm As String
End Class

Remarks

This event fires with information about the key used to encrypt the data. This may be used to help identify the Key or Certificate to load in order to decrypt the message. This event fires when Decrypt or Parse is called.

KeyId is the Id of the key as supplied by the entity that created the message. This may be empty.

Algorithm is the encryption algorithm used to encrypt the data.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X.509 public key.

• C#
• VB.NET

public Certificate(byte[] certificateData);

Public Certificate(ByVal CertificateData As Byte())

Parses CertificateData as an X.509 public key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CryptoAPI option. The default value is True (the key is persisted). "Thumbprint" - an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject, string configurationString);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. StoreBlob is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN).

• C#
• VB.NET

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

Public Certificate(ByVal CertStoreType As CertStoreTypes, ByVal StoreBlob As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or Base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

HeaderParam Type

The JOSE header parameter.

Remarks

This type holds the JOSE header parameters. The fields define the name, value, and data type of the parameter.

Fields

Constructors

• C#
• VB.NET

public HeaderParam();

Public HeaderParam()

Creates a new header parameter with no name or value.

• C#
• VB.NET

public HeaderParam(string name, string value);

Public HeaderParam(ByVal Name As String, ByVal Value As String)

Creates a new header parameter. The DataType of the value will be a String.

• C#
• VB.NET

public HeaderParam(string name, string value, int dataType);

Public HeaderParam(ByVal Name As String, ByVal Value As String, ByVal DataType As Integer)

Creates a new header parameter with the specified DataType.

Config Settings (JWE Component)

JWE Config Settings

Base Config Settings

Trappable Errors (JWE Component)

JWE Errors