IPWorks S/MIME 2020 .NET Edition

Questions / Feedback?

SMIME 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.

SMIME Configuration Settings

ApplyB64Encoding:   Instructs the component to base64 encode the message when signing or encrypting.

This setting allows you to control the base64 encoding of the resulting message. By default, this value is true, and the message will be base64 encoded when signing or encrypting.

NOTE: When signing, this config may only be used when DetachedSignature is false.

CloseInputStreamAfterProcess:   Determines whether or not the input stream is closed after processing.

Determines whether or not the input stream set by SetInputStream is closed after processing is complete. The default value is False.

CloseOutputStreamAfterProcess:   Determines whether or not the output stream is closed after processing.

Determines whether or not the output stream set by SetOutputStream is closed after processing is complete. The default value is False.

CSP:   The Cryptographic Service Provider.

For the Win32 editions, the name of the Cryptographic Service Provider used to provide access to encryption/decryption and signature operations.

NOTE: This config may only be used when the UseCryptoAPI is true.

GenerateSignatureTimestamp:   Whether to generate timestamps in signatures.

If GenerateSignatureTimestamp is True, a timestamp will be generated and added to all signatures created by the component.

The default value is True.

IncludeHeaders:   Tells the component whether to include the headers when encoding the message.

If true, the component will include the headers when Sign, Encrypt, or SignAndEncrypt are called. If false, only the message will be encoded.

The default value for IncludeHeaders is false.

IncludeInternalHeaders:   Tells the component whether or not to include the internal headers when encoding the message.

If true, the component will include the internal message part headers when Sign, Encrypt, or SignAndEncrypt are called. When set to false, only the message will be encoded.

The default value for IncludeInternalHeaders is true.

InputContentTransferEncoding:   Sets the Content-Transfer-Encoding for the signed message.

This setting specifies the Content-Transfer-Encoding header value in signed messages. By default the component will automatically determine the Content-Transfer-Encoding based on the file extension set in InputFile, however this setting may be set to override the determined value or to specify a value if data is read from InputMessage.

If no value is specified and a value cannot be automatically determined the default value 7bit will be used.

Note: This setting is only applicable when calling Sign or SignAndEncrypt and DetachedSignature is True.

InputContentType:   Sets the Content-Type for the signed message.

This setting specifies the Content-Type header value in signed messages. By default the component will automatically determine the Content-Type based on the file extension set in InputFile, however this setting may be set to override the determined value or to specify a value if data is read from InputMessage.

If no value is specified and a value cannot be automatically determined the default value text/plain; charset="iso-8859-1" will be used.

Note: This setting is only applicable when calling Sign or SignAndEncrypt and DetachedSignature is True.

InputMessageEncrypted:   Whether or not the input message is encrypted.

This will return true if the input message appears to be encrypted according to the value of InputMessageHeaders.

InputMessageSigned:   Whether or not the input message is signed.

This will return true if the input message appears to be signed according to the value of InputMessageHeaders.

OAEPMGF1HashAlgorithm:   The MGF1 hash algorithm used with OAEP.

This setting specifies the MGF1 hash algorithm used when UseOAEP is set to True. The default value is "SHA256". Possible values are:

  • "SHA1"
  • "SHA224"
  • "SHA256" (default)
  • "SHA384"
  • "SHA512"
  • "RIPEMD160"
  • "MD2"
  • "MD5"
  • "MD5SHA1"
OAEPParams:   The hex encoded OAEP parameters.

This setting optionally specifies OAEP parameters to be used when UseOAEP is set to True. The specified value should be hex encoded.

OAEPRSAHashAlgorithm:   The RSA hash algorithm used with OAEP.

This setting specifies thet RSA Hash Algorithm used when UseOAEP is set to True. The default value is "SHA256". Possible values are:

  • "SHA1"
  • "SHA224"
  • "SHA256" (default)
  • "SHA384"
  • "SHA512"
  • "RIPEMD160"
  • "MD2"
  • "MD5"
  • "MD5SHA1"
ParseInternalHeaders:   Tells the component whether or not to parse the message part headers when decrypting a message.

If true, the component will parse the internal message part headers when Decrypt, or DecryptAndVerifySignature are called. These headers will be placed in the InternalHeaders property. If false, the entire message will be decoded.

The default value for ParseInternalHeaders is true.

RecipientCert:   Used to specify the public certificate when using a PEM key to decrypt.

When decrypting, the component must search through the Recipient Info collection to find which encrypted key to use for decryption. Since PEM keys do not contain a serial number or any additional information about the key itself, the public key associated with this private key must be supplied.

This configuration may be set to the entire blob of the public certificate the component should use to select the correct recipient encrypted key to use for decryption.

RecipientCertFile:   Used to specify the public certificate file when using a PEM key to decrypt.

When decrypting, the component must search through the Recipient Info collection to find which encrypted key to use for decryption. Since PEM keys do not contain a serial number or any additional information about the key itself, the public key associated with this private key must be supplied.

This configuration may be set to the file which contains the public certificate the component should use to select the correct recipient encrypted key to use for decryption.

RecipientInfoType:   The type of signer information to include in the signed message.

This setting specifies which type of information about the recipient's encryption certificate is included in the encrypted message. Possible values are:

  • 0 (issuerAndSerialNumber - default)
  • 1 (subjectKeyIdentifier)

Note: When subjectKeyIdentifier is selected the recipient's encryption certificate must contain the subjectKeyIdentifier extension.

SignerInfoType:   The type of signer information to include in the signed message.

This setting specifies which type of information about the signer certificate is included in the signed message. Possible values are:

  • 0 (issuerAndSerialNumber - default)
  • 1 (subjectKeyIdentifier)

Note: When subjectKeyIdentifier is selected the signing certificate must contain the subjectKeyIdentifier extension.

UseAlgorithmOIDs:   Whether OIDs are used when providing information about the algorithms.

This setting controls whether the EncryptionAlgorithm parameter of the RecipientInfo event is populated with the name of the algorithm such as 3DES or the corresponding OID such as 1.2.840.113549.3.7.

The default value is False and the name of the algorithm is used. Set this to True to use the OIDs instead.

UseCryptoAPI:   Whether to use the Microsoft Crypto API for cryptographic message generation.

If UseCryptoAPI is set to true, the component will use the Microsoft Crypto API to process encrypted and/or signed data. Note that compression will be impossible in this case.

If set to false (the default), the component will use its internal S/MIME engine.

VerifyCertChain:   Whether to verify the certificate chain of the certificate used to sign the message.

This setting specifies whether the signer certificate used to sign the message is validated when VerifySignature is called.

If set to True the component will verify that the issuer(s) of the signer certificate are valid and trusted on the system.

If set to False (default) the certificate chain is not validated.

This setting does not affect whether the digital signature of the signed message is verified. This setting affects only whether the trust and validity of the signer certificate chain is evaluated.

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 S/MIME 2020 .NET Edition - Version 20.0 [Build 8154]