IPWorks Encrypt 2020 Kotlin Edition

Questions / Feedback?

CMS Component

Properties   Methods   Events   Configuration Settings   Errors  

The CMS component is used to digitally sign, encrypt, verify, and decrypt data.

Syntax

ipworksencrypt.Cms

Remarks

The CMS component implements the Cryptographic Message Syntax and allow for various cryptographic operations to be performed on data including:

The component can generate and consume message in a variety of formats including PEM, DER (Binary), and SMIME. The EncryptionAlgorithm and SignatureHashAlgorithm are fully configurable and support a variety of industry standard encryption and hash algorithms.

The component supports additional functionality such as Compression, OAEP, and PSS. The GetRecipientInfo and GetSignerCertInfo methods as well as the RecipientInfo and SignerCertInfo events allow for a dynamic and flexible approach to message processing. Certificate may be loaded ahead of time or as-needed from the events.

Signing Notes

Sign digitally signs the input data with the the specified certificate(s). Certificates are specified by calling AddCertificate or setting the Certificates property.

OutputFormat specifies the encoding of the output message. Valid values are PEM, DER, and SMIME. IncludeCertificates specifies whether the public certificate is included in the signed message. Additional settings allow further configuration. The following properties are applicable when calling this method:

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:

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

Sign and Verify a message

Cms cms = new Cms();
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.InputMessage = "My Data";
cms.Sign();

string signedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;
Sign and Verify a message - DER Output Format
Cms cms = new Cms();
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.InputMessage = "My Data";
cms.OutputFormat = "DER";
cms.Sign();

byte[] signedMessage = cms.OutputMessageB; //Binary output

cms = new Cms();
cms.InputMessageB = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;
Sign and Verify a message - Detached Signature
Cms cms = new Cms();
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.InputMessage = "My Data";
cms.DetachedSignature = true;
cms.Sign();

string signature = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = "My Data";
cms.DetachedSignatureData = signature;
cms.DetachedSignature = true;
cms.VerifySignature();
Sign and Verify a message - Multiple Signatures
Cms cms = new Cms();
cms.InputMessage = "My Data";
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test2.pfx", "password2", "*"));
cms.Sign();

string signedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;
Sign and Verify a message - No Included Certificate
Cms cms = new Cms();
cms.InputMessage = "My Data";
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.IncludeCertificates = CmsIncludeCertificates.icsNone;
cms.Sign();

string signedMessage = cms.OutputMessage;

cms = new Cms();
cms.OnSignerCertInfo += (s, e) => {
  Console.WriteLine(e.Issuer);
  Console.WriteLine(e.SerialNumber);
  if (e.Issuer == "CN=100") //Identify the certificate to load based on event params
  {
    //Load the correct signer certificate.
    cms.SignerCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
  }
};
cms.InputMessage = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;

Encryption Notes

Encrypt encrypts the input data with the the specified certificate(s). Certificates are specified by calling AddRecipientCert or setting the RecipientCerts property.

OutputFormat specifies the encoding of the output message. Valid values are PEM, DER, and SMIME. Additional settings allow further configuration. The following properties are applicable when calling this method:

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:

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

Encrypt and Decrypt a message

Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.InputMessage = "My Data";
cms.Encrypt();

string encryptedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = encryptedMessage;
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;
Encrypt and Decrypt a message - DER Output Format
Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.InputMessage = "My Data";
cms.OutputFormat = "DER";
cms.Encrypt();

byte[] encryptedMessage = cms.OutputMessageB; //Binary output

cms = new Cms();
cms.InputMessageB = encryptedMessage;
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;
Encrypt and Decrypt - Multiple Recipients
Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test2.cer", "", "*"));
cms.InputMessage = "My Data";
cms.Encrypt();

string encryptedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = encryptedMessage;
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;
Encrypt and Decrypt - Get Recipient Info
Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.InputMessage = "My Data";
cms.Encrypt();

string encryptedMessage = cms.OutputMessage;

//If the recipient certificate is not known ahead of time the GetRecipientInfo method may be called
//to find information about the certificate.
cms = new Cms();
cms.InputMessage = encryptedMessage;
cms.OnRecipientInfo += (s, e) => {
  Console.WriteLine(e.SerialNumber);
  Console.WriteLine(e.Issuer);
  if (e.Issuer == "CN=100") //Identify the certificate to load based on event params
  {
    cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
  }
};

cms.GetRecipientInfo();
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;

Signature Verification Notes

VerifySignature verifies the signature of the input message.

In order to perform signature verification the public signer's certificate must be present or explicitly specified. In many cases the certificate itself is included in the input message and a certificate does not need to explicitly be set. If a certificate does need to be set for signature verification the certificate may be specified by calling AddRecipientCert or setting RecipientCerts.

When this method is called the SignerCertInfo event fires once for each signature on the message. This event provides details about the signer certificate, as well as the signer certificate itself (if present). The information provided via SignerCertInfo may be used to load an appropriate certificate for verification from within the event. If the CertEncoded parameter of SignerCertInfo is populated the certificate required for verification is already present in the message.

The following property are applicable when calling this method:

If the input message is a detached signature, the original data that was signed must be specified in DetachedSignatureData. In addition the DetachedSignature property must be set to True to instruct the component to treat the input message as a detached signature.

If the input message is compressed EnableCompression must be set to True before calling this method.

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:

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

Sign and Verify a message

Cms cms = new Cms();
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.InputMessage = "My Data";
cms.Sign();

string signedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;
Sign and Verify a message - DER Output Format
Cms cms = new Cms();
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.InputMessage = "My Data";
cms.OutputFormat = "DER";
cms.Sign();

byte[] signedMessage = cms.OutputMessageB; //Binary output

cms = new Cms();
cms.InputMessageB = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;
Sign and Verify a message - Detached Signature
Cms cms = new Cms();
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.InputMessage = "My Data";
cms.DetachedSignature = true;
cms.Sign();

string signature = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = "My Data";
cms.DetachedSignatureData = signature;
cms.DetachedSignature = true;
cms.VerifySignature();
Sign and Verify a message - Multiple Signatures
Cms cms = new Cms();
cms.InputMessage = "My Data";
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test2.pfx", "password2", "*"));
cms.Sign();

string signedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;
Sign and Verify a message - No Included Certificate
Cms cms = new Cms();
cms.InputMessage = "My Data";
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.IncludeCertificates = CmsIncludeCertificates.icsNone;
cms.Sign();

string signedMessage = cms.OutputMessage;

cms = new Cms();
cms.OnSignerCertInfo += (s, e) => {
  Console.WriteLine(e.Issuer);
  Console.WriteLine(e.SerialNumber);
  if (e.Issuer == "CN=100") //Identify the certificate to load based on event params
  {
    //Load the correct signer certificate.
    cms.SignerCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
  }
};
cms.InputMessage = signedMessage;
cms.VerifySignature();

string plaintextMessage = cms.OutputMessage;

Decryption Notes

Decrypt decrypts the input data with the specified certificate. Certificates are specified by calling AddCertificate or setting the Certificates property.

If the certificate used to encrypt the message is not known ahead of time GetRecipientInfo may be called prior to calling Decrypt to obtain information about the recipient (the entity the for which the message was encrypted). If GetRecipientInfo is called, the RecipientInfo event is fired with information about the recipient which may be used to load an appropriate decryption certificate.

The following properties are applicable when calling this method:

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:

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

Encrypt and Decrypt a message

Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.InputMessage = "My Data";
cms.Encrypt();

string encryptedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = encryptedMessage;
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;
Encrypt and Decrypt a message - DER Output Format
Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.InputMessage = "My Data";
cms.OutputFormat = "DER";
cms.Encrypt();

byte[] encryptedMessage = cms.OutputMessageB; //Binary output

cms = new Cms();
cms.InputMessageB = encryptedMessage;
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;
Encrypt and Decrypt - Multiple Recipients
Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test2.cer", "", "*"));
cms.InputMessage = "My Data";
cms.Encrypt();

string encryptedMessage = cms.OutputMessage;

cms = new Cms();
cms.InputMessage = encryptedMessage;
cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;
Encrypt and Decrypt - Get Recipient Info
Cms cms = new Cms();
cms.RecipientCerts.Add(new Certificate(CertStoreTypes.cstPublicKeyFile, @"C:\temp\test.cer", "", "*"));
cms.InputMessage = "My Data";
cms.Encrypt();

string encryptedMessage = cms.OutputMessage;

//If the recipient certificate is not known ahead of time the GetRecipientInfo method may be called
//to find information about the certificate.
cms = new Cms();
cms.InputMessage = encryptedMessage;
cms.OnRecipientInfo += (s, e) => {
  Console.WriteLine(e.SerialNumber);
  Console.WriteLine(e.Issuer);
  if (e.Issuer == "CN=100") //Identify the certificate to load based on event params
  {
    cms.Certificates.Add(new Certificate(CertStoreTypes.cstPFXFile, @"C:\temp\test.pfx", "password", "*"));
  }
};

cms.GetRecipientInfo();
cms.Decrypt();

string plaintextMessage = cms.OutputMessage;

Property List


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

CertificatesA collection of certificates used for signing and decryption.
DetachedSignatureSpecifies whether to include a detached signature when signing a message.
DetachedSignatureDataThe detached signature.
EnableCompressionSpecifies whether to compress the message.
EncryptionAlgorithmThe algorithm used for encryption.
IncludeCertificatesSpecifies whether to include the signer's certificate with the signed message.
InputFileThe file to process.
InputMessageThe message to process.
OutputFileThe output file.
OutputFormatSpecifies the output format.
OutputMessageThe output message after processing.
RecipientCertsThe collection of recipient certificates.
SignatureHashAlgorithmThe signature hash algorithm used during signing.
SignerCertsThe collection of signer certificates.
UseOAEPWhether to use Optimal Asymmetric Encryption Padding (OAEP).
UsePSSWhether to use RSA-PSS during signing and verification.

Method List


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

AddCertificateUsed to add certificates for signing.
AddRecipientCertUsed to add recipient certificates used to encrypt messages.
ConfigSets or retrieves a configuration setting.
DecryptDecrypts the current message.
DecryptAndVerifySignatureDecrypts and verifies the signature of the current message.
EncryptEncrypts the current message.
GetRecipientInfoGets the recipient certificate information for an encrypted message.
GetSignerCertInfoGets the signature information for an signed message.
ResetResets the component properties.
SetInputStreamSets the stream from which the component will read data to encode or decode.
SetOutputStreamSets the stream to which the component will read data to encode or decode.
SignSigns the current message.
SignAndEncryptSigns and encrypts the current message.
VerifySignatureVerifies the signature of the current message.

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.

ErrorInformation about errors during data delivery.
LogFires with log information during processing.
RecipientInfoFired for each recipient certificate of the encrypted message.
SignerCertInfoFired during verification of the signed message.

Configuration Settings


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

CloseInputStreamAfterProcessDetermines whether or not the input stream is closed after processing.
CloseOutputStreamAfterProcessDetermines whether or not the output stream is closed after processing.
CompressBeforeSignSpecifies whether to compress before signing.
ContentTypeOIDSpecifies the oid for content type.
CSPThe Cryptographic Service Provider.
GenerateSignatureTimestampWhether to generate timestamps in signatures.
IncludeHeadersTells the component whether to include the headers when encoding the message.
IncludeInternalHeadersTells the component whether or not to include the internal headers when encoding the message.
InputContentTransferEncodingSets the Content-Transfer-Encoding for the signed message.
InputContentTypeSets the Content-Type for the signed message.
InputMessageHeadersMessage headers.
LogDirectoryThe directory on disk where debug logs are written.
LogFilenameThe base filename to use with LogDirectory.
LogLevelThe level of detail for log messages.
OAEPMGF1HashAlgorithmThe MGF1 hash algorithm used with OAEP.
OAEPParamsThe hex encoded OAEP parameters.
OAEPRSAHashAlgorithmThe RSA hash algorithm used with OAEP.
OutputMessageHeadersThe SMIME headers of the output message.
RecipientInfoTypeThe type of signer information to include in the signed message.
SignatureTimestampThe signature timestamp in the signed message.
SignerInfoTypeThe type of signer information to include in the signed message.
UseAlgorithmOIDsWhether OIDs are used when providing information about the algorithms.
BuildInfoInformation about the product's build.
GUIAvailableTells the component whether or not a message loop is available for processing events.
LicenseInfoInformation about the current license.
UseDaemonThreadsWhether threads created by the component are daemon threads.
UseInternalSecurityAPITells the component whether or not to use the system security libraries or an internal implementation.

Copyright (c) 2021 /n software inc. - All rights reserved.
IPWorks Encrypt 2020 Kotlin Edition - Version 20.0 [Build 7941]