CMS Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

class ipworksencrypt.CMS

Remarks

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

• sign
• verify_signature
• encrypt
• decrypt
• sign_and_encrypt
• decrypt_and_verify_signature

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

The class supports additional functionality such as Compression, OAEP, and PSS. The get_recipient_info and get_signer_cert_info methods as well as the on_recipient_info and on_signer_cert_info 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 add_certificate or setting the certificates property.

output_format specifies the encoding of the output message. Valid values are PEM, DER, and SMIME. include_certificates 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:

• certificates (required)
• detached_signature
• enable_compression
• GenerateSignatureTimestamp
• include_certificates
• output_format
• signature_hash_algorithm
• use_pss

Input and Output Properties

The class 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:

• input_file
• input_message

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

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 add_recipient_cert or setting the recipient_certs property.

output_format 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:

• recipient_certs (required)
• encryption_algorithm
• output_format
• use_oaep

Input and Output Properties

The class 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:

• input_file
• input_message

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

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

verify_signature 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 add_recipient_cert or setting recipient_certs.

When this method is called the on_signer_cert_info 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 on_signer_cert_info may be used to load an appropriate certificate for verification from within the event. If the CertEncoded parameter of on_signer_cert_info is populated the certificate required for verification is already present in the message.

The following property are applicable when calling this method:

• detached_signature
• detached_signature_data
• enable_compression
• signer_certs

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

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

Input and Output Properties

The class 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:

• input_file
• input_message

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

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 add_certificate or setting the certificates property.

If the certificate used to encrypt the message is not known ahead of time get_recipient_info may be called prior to calling decrypt to obtain information about the recipient (the entity the for which the message was encrypted). If get_recipient_info is called, the on_recipient_info 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:

• certificates (Required)

Input and Output Properties

The class 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:

• input_file
• input_message

When a valid source is found the search stops. The order in which the output properties are checked is as follows:

• output_file
• output_message: The output data is written to this property if no other destination is specified.

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 class with short descriptions. Click on the links for further details.

cert_count	The number of records in the Cert arrays.
cert_encoded	The certificate (PEM/base64 encoded).
cert_store	The name of the certificate store for the client certificate.
cert_store_password	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
cert_store_type	The type of certificate store for this certificate.
cert_subject	The subject of the certificate used for client authentication.
detached_signature	Specifies whether to include a detached signature when signing a message.
detached_signature_data	The detached signature.
enable_compression	Specifies whether to compress the message.
encryption_algorithm	The algorithm used for encryption.
include_certificates	Specifies whether to include the signer's certificate with the signed message.
input_file	The file to process.
input_message	The message to process.
output_file	The output file.
output_format	Specifies the output format.
output_message	The output message after processing.
recipient_cert_count	The number of records in the RecipientCert arrays.
recipient_cert_encoded	The certificate (PEM/base64 encoded).
recipient_cert_store	The name of the certificate store for the client certificate.
recipient_cert_store_password	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
recipient_cert_store_type	The type of certificate store for this certificate.
recipient_cert_subject	The subject of the certificate used for client authentication.
signature_hash_algorithm	The signature hash algorithm used during signing.
signer_cert_count	The number of records in the SignerCert arrays.
signer_cert_encoded	The certificate (PEM/base64 encoded).
signer_cert_store	The name of the certificate store for the client certificate.
signer_cert_store_password	If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
signer_cert_store_type	The type of certificate store for this certificate.
signer_cert_subject	The subject of the certificate used for client authentication.
use_oaep	Whether to use Optimal Asymmetric Encryption Padding (OAEP).
use_pss	Whether to use RSA-PSS during signing and verification.

Method List

---

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

add_certificate	Used to add certificates for signing.
add_recipient_cert	Used to add recipient certificates used to encrypt messages.
config	Sets or retrieves a configuration setting.
decrypt	Decrypts the current message.
decrypt_and_verify_signature	Decrypts and verifies the signature of the current message.
encrypt	Encrypts the current message.
get_recipient_info	Gets the recipient certificate information for an encrypted message.
get_signer_cert_info	Gets the signature information for an signed message.
reset	Resets the class properties.
sign	Signs the current message.
sign_and_encrypt	Signs and encrypts the current message.
verify_signature	Verifies the signature of the current message.

Event List

---

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

on_error	Information about errors during data delivery.
on_log	Fires with log information during processing.
on_recipient_info	Fired for each recipient certificate of the encrypted message.
on_signer_cert_info	Fired during verification of the signed message.

Configuration Settings

---

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

CompressBeforeSign	Specifies whether to compress before signing.
ContentTypeOID	Specifies the oid for content type.
CSP	The Cryptographic Service Provider.
GenerateSignatureTimestamp	Whether to generate timestamps in signatures.
IncludeHeaders	Tells the class whether to include the headers when encoding the message.
IncludeInternalHeaders	Tells the class whether or not to include the internal headers when encoding the message.
InputContentTransferEncoding	Sets the Content-Transfer-Encoding for the signed message.
InputContentType	Sets the Content-Type for the signed message.
InputMessageHeaders	Message headers.
LogDirectory	The directory on disk where debug logs are written.
LogFilename	The base filename to use with LogDirectory.
LogLevel	The level of detail for log messages.
OAEPMGF1HashAlgorithm	The MGF1 hash algorithm used with OAEP.
OAEPParams	The hex encoded OAEP parameters.
OAEPRSAHashAlgorithm	The RSA hash algorithm used with OAEP.
OutputMessageHeaders	The SMIME headers of the output message.
RecipientInfoType	The type of signer information to include in the signed message.
SignatureTimestamp	The signature timestamp in the signed message.
SignerInfoType	The type of signer information to include in the signed message.
UseAlgorithmOIDs	Whether OIDs are used when providing information about the algorithms.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.