IPWorks Encrypt 2020 Java Edition

Questions / Feedback?

Ecc Configuration

The class 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 class, access to these internal properties is provided through the Config method.

ECC Configuration Settings

AppendSecret:   An optional string to append to the secret agreement.

This setting specifies an optional string to append to the secret agreement before hashing it. This is applicable when calling ComputeSecret.

Note: This is not applicable when ComputeSecretKDF is set to 12 (ekdTLS).

CNGECDHKey:   The CNG ECDH key.

This setting may be set to specify the key exported from Microsoft's CNG before calling ComputeSecret. If key data was obtained from Microsoft's CNG API it can be hex encoded and supplied here. The class will use this key when ComputeSecret is called.

CNGECDSAKey:   The CNG ECDSA key.

This setting may be set to specify the key exported from Microsoft's CNG before calling VerifySignature. If key data was obtained from Microsoft's CNG API it can be hex encoded and supplied here. The class will use this key when VerifySignature is called.

ConcatAlgorithmId:   Specifies the AlgorithmId subfield of the OtherInfo field.

This setting specifies the AlgorithmId subfield of the OtherInfo field as described in the publication "NIST SP 800-56A" section 5.8.1. The value supplied to this setting must be a hex encoded string of the subfield data.

This setting is required when ComputeSecretKDF is set to ekdConcat. This setting is only applicable when calling ComputeSecret.

ConcatHashAlgorithm:   The hash algorithm to use when ComputeSecretKDF is Concat.

This optionally specifies the hash algorithm to use when ComputeSecretKDF is set to ekdConcat. Possible values are:

  • SHA1
  • SHA224
  • SHA256 (default)
  • SHA384
  • SHA512
  • RIPEMD160
ConcatPartyUInfo:   Specifies the PartyUInfo subfield of the OtherInfo field.

This setting specifies the PatyUInfo subfield of the OtherInfo field as described in the publication "NIST SP 800-56A" section 5.8.1. The value supplied to this setting must be a hex encoded string of the subfield data.

This setting is required when ComputeSecretKDF is set to ekdConcat. This setting is only applicable when calling ComputeSecret.

ConcatPartyVInfo:   Specifies the PartyVInfo subfield of the OtherInfo field.

This setting specifies the PartyVInfo subfield of the OtherInfo field as described in the publication "NIST SP 800-56A" section 5.8.1. The value supplied to this setting must be a hex encoded string of the subfield data.

This setting is required when ComputeSecretKDF is set to ekdConcat. This setting is only applicable when calling ComputeSecret.

ConcatSuppPrivInfo:   Specifies the SuppPrivInfo subfield of the OtherInfo field.

This setting specifies the SuppPrivInfo subfield of the OtherInfo field as described in the publication "NIST SP 800-56A" section 5.8.1. The value supplied to this setting must be a hex encoded string of the subfield data.

This setting is optional when ComputeSecretKDF is set to ekdConcat. This setting is only applicable when calling ComputeSecret.

ConcatSuppPubInfo:   Specifies the SuppPubInfo subfield of the OtherInfo field.

This setting specifies the SuppPubInfo subfield of the OtherInfo field as described in the publication "NIST SP 800-56A" section 5.8.1. The value supplied to this setting must be a hex encoded string of the subfield data.

This setting is optional when ComputeSecretKDF is set to ekdConcat. This setting is only applicable when calling ComputeSecret.

ECDSASignatureFormat:   The format of the HashSignature when using ECDSA keys.

This setting specifies the format of HashSignature when signing with ECDSA keys. The way the HashSignature parameters are represented can be changed to be interoperable with other implementations. Possible values are:

  • 0 (Concatenated - default)
  • 1 (ASN)

Note: This setting is only applicable when Algorithm is set to secp256r1, secp384r1, or secp521r1.

EdDSAContext:   A hex encoded string holding the bytes of the context when signing or verifying with ed25519ctx.

This setting specifies up to 255 bytes of context data as a hex encoded string for during signing and verifying.

This setting is only applicable when Algorithm is set to ed25519 or ed448. When this setting is specified and the Algorithm is ed25519 and HashEdDSA is False the class will automatically use ed25519ctx.

If this value is specified before calling Sign, it must also be set prior to calling VerifySignature.

EncryptionKeySize:   The encryption key size.

This setting specifies the AES encryption key size in bits when EncryptionAlgorithm is set to AES. Possible values are:

  • 128
  • 192
  • 256 (default)
This setting is only applicable when calling Encrypt.
HMACKey:   A key to use when generating a Hash-based Message Authentication Code (HMAC).

This key is incorporated into the hashing process to add entropy to the resulting hash code, making the plaintext harder to guess and increasing the message security. The value supplied here must be hex encoded.

This is only applicable when calling ComputeSecret.

HMACKeySize:   Specifies the HMAC key size to be used during encryption.

This setting optionally specifies the HMAC key size to be used during encryption and decryption. If set to 0 (default) the class will automatically select the key size based on the algorithm specified in HMACAlgorithm.

This setting is only applicable when calling Encrypt or Decrypt.

HMACOptionalInfo:   Optional data to be used during encryption and decryption during the HMAC step.

This setting optionally specifies data to be used with the specified HMACAlgorithm as part of the encryption and decryption process. This is additional data known to both parties that is included while performing the HMAC operation.

The value specified in this setting must a hex string.

If specified this must be set before calling both Encrypt and Decrypt.

KDFOptionalInfo:   Optional data to be used during encryption and decryption during the key derivation step.

This setting optionally specifies data to be used with the specified KDF as part of the encryption and decryption process. This is additional data known to both parties that is included while performing key derivation.

The value specified in this setting must a hex string.

If specified this must be set before calling both Encrypt and Decrypt.

PrependSecret:   An optional string to prepend to the secret agreement.

This setting specifies an optional string to prepend to the secret agreement before hashing it. This is applicable when calling ComputeSecret.

Note: This is not applicable when ComputeSecretKDF is set to 12 (ekdTLS).

StrictKeyValidation:   Whether to validate provided public keys based on private keys.

This setting performs additional checks prior to using specified keys to validate the public key corresponds to the provided private key.

When using keys with the algorithm ed25519, ed448, X25519, or X448 the class will calculate the public key based on the provided private key and compare it to the provided public key to ensure they match.

When using keys with the algorithm secp256r1, secp384r1, or secp521r1 the class will perform calculations to verify the public key is a point on the curve. The class will also calculate the public key based on the provided private key and compare it to the provided public key to ensure they match.

The default value is False and the class will use the public and private keys as provided without any additional checks.

TLSLabel:   The TLS PRF label.

This setting specifies a string representing the PRF label. This setting is required when ComputeSecretKDF set to 12 (ekdTLS). It is only applicable when calling ComputeSecret.

TLSSeed:   The TLS PRF Seed.

This setting specifies the hex encoded TLS PRF Seed. The seed value must be 64 bytes in length before hex encoding. This setting is required when ComputeSecretKDF set to 12 (ekdTLS). It is only applicable when calling ComputeSecret.

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 class 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 class 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 class 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 class 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).
UseDaemonThreads:   Whether threads created by the class are daemon threads.

If set to True (default), when the class creates a thread the thread's Daemon property will be explicitly set to True. When set to False the class will not set the Daemon property on the created thread. The default value is True.

UseInternalSecurityAPI:   Tells the class whether or not to use the system security libraries or an internal implementation.

By default the class will use the system security libraries to perform cryptographic functions. Setting this to True tells the class to use the internal implementation instead of using the system's security API.

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