IPWorks Encrypt 2020 .NET Edition

Questions / Feedback?

JWS Configuration

The component accepts one or more of the following configuration settings. Configuration 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.

JWS Configuration Settings

AllowedSigningAlgorithms:   Allowed signing algorithms when StrictValidation is set to True.

This setting specifics a comma separated list of algorithms that are allowed when StrictValidation is set to true. This allows multiple signing algorithms to be considered acceptable during validation. This setting is only applicable when StrictValidation is set to true. Possible values:

  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512
  • PS256
  • PS384
  • PS512

Example value: HS512,HS256.

CloseInputStreamAfterProcess:   Whether to close the input stream after processing.

This setting specifies whether the stream set by SetInputStream is closed after processing the message. The default value is True.

CloseOutputStreamAfterProcess:   Whether to close the output stream after processing.

This setting specifies whether the stream set by SetOutputStream is closed after processing the message. The default value is True.

IncludeCertificateFormat:   The certificate values to include in the signed message (if any).

This setting specifies whether information about the Certificate is included in the signed message. When specified, the value here determines the format of the included certificate information. The certificate information is included as a standard JWS header parameter.

Multiple formats may be included in the signed message. The value specified should be the binary 'OR' of one or more of the following values:

Value Description JWS Header Param
0 (0x00 - default) None
1 (0x01) X.509 Certificate Chain x5c
2 (0x02) X.509 Certificate SHA-1 Thumbprint (Base64-URL encoded) x5t
4 (0x04) X.509 Certificate SHA-256 Thumbprint (Base64-URL encoded) x5t#S256

Note: When including the certificate chain (0x01) the public certificate of Certificate will automatically be included. IssuerCerts may also be set to the public issuer certificates that will be used when building the chain to include.

For instance, to include both the certificate chain and SHA-256 thumbprint of the Certificate set this to 5.

IssuerCerts:   A collection of issuer certificates used with IncludeCertificateFormat.

This setting optionally specifies one or more issuer certificates that may be used by the component when IncludeCertificateFormat is specified. Note that the issuer certificates specified here are used as a store of potential issuer certificates. At runtime the component will inspect the Certificate value and add the relevant issuer certificates that are present in this property.

The format of the value must be one or more PEM encoded certificates with headers and footers. For instance to include 2 issuer certificates the value may be:

-----BEGIN CERTIFICATE-----
MIIBujCCASOgAwIBAgICA+kwDQYJKoZIhvcNAQELBQAwHTEbMBkGA1UEAxMSbnVuaXRDZXJ0
Q2hhaW5Sb290MCAXDTE4MTAxNTA5MDAxN1oYDzIxMTgwOTIxMDkwMDE3WjAmMSQwIgYDVQQD
...
Tr+wi0ouNo7ifWRcE83Z15PhfGn1nkfxMYj4rya5n+V0RVVcgFUdiolCI5o/sYq503a7kH16
JSF5Zw+TiMz/COM8R94=
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIBsTCCARqgAwIBAgICA+gwDQYJKoZIhvcNAQELBQAwHTEbMBkGA1UEAxMSbnVuaXRDZXJ0
Q2hhaW5Sb290MCAXDTE4MTAxNTA5MDAxN1oYDzIxMTgwOTIxMDkwMDE3WjAdMRswGQYDVQQD
...
5u2K9PuJ3ySgL7AvYsqbB/e0/gw8j253SOU+gNTpFahOJsLGEJ43CRtaowkLnWEzs+OPnRfw
iQmqruw=
-----END CERTIFICATE-----

KeyEncoding:   The encoding of the Key value.

This setting specifies the encoding that has been applied to the Key. value prior to providing it to the component. The Key is typically represented as an array of bytes, however in some cases the key value may have been encoded. As a matter of convenience the component will accept the key with an encoding already applied. The component will decode the key value according the to the value specified here before processing. Possible values are:

  • 0 (none - default)
  • 1 (base64)

RawHeader:   Holds the raw JOSE header.

This setting may be queried after calling Sign or Verify to obtain the raw JOSE header. This returns a JSON string like:

{"alg":"ES384","kid":"myKeyId"}

SerializationType:   Determines the serialization type to use when reading and writing JWS content.

This setting is used to control the serialization type the component uses when reading and writing JWS content. Possible values are:

  • 0 (default): Compact serialization (content is serialized as a single base64url-encoded string).
  • 1: Standard JSON serialization.
  • 2: Flattened JSON serialization.
StrictValidation:   Requires a specific algorithm when verifying signatures.

If set to True the component will validate that the Algorithm in the JWS message matches the value specified in the Algorithm property. If it does not an error is thrown. By default this is False and the algorithm is read and used automatically from the message. Enabling this setting provides a way to require a specific algorithm when calling VerifySignature.

Base Configuration Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

GUIAvailable:   Tells the component whether or not a message loop is available for processing events.

In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The component will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GUIAvailable to false will ensure that the component does not attempt to process external events.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a component is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g. RuntimeLicense, License File).
  • License Type: The type of license installed (e.g. Royalty Free, Single Server).
UseInternalSecurityAPI:   Tells the component whether or not to use the system security libraries or an internal implementation.

By default the component will use the system security libraries to perform cryptographic functions. When set to False calls to unmanaged code will be made. In certain environments this is not desirable. To use a completely managed security implementation set this setting to True. Setting this to True tells the component to use the internal implementation instead of using the system's security API.

Note: This setting is static. The value set is applicable to all components used in the application.

When this value is set the product's system DLL is no longer required as a reference, as all unmanaged code is stored in that file.

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