CMS Class
Properties Methods Events Configuration Settings Errors
The CMS class is used to digitally sign, encrypt, verify, and decrypt data.
Syntax
IPWorksEncryptCMS
IPWorksEncryptCMSSwift
Remarks
The CMS class implements the Cryptographic Message Syntax and allow for various cryptographic operations to be performed on data including:
The class 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 class 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:
- Certificates (required)
- DetachedSignature
- EnableCompression
- GenerateSignatureTimestamp
- IncludeCertificates
- OutputFormat
- SignatureHashAlgorithm
- UsePSS
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:
When a valid source is found the search stops. The order in which the output properties are checked is as follows:
- OutputFile
- OutputMessage: 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 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:
- RecipientCerts (required)
- EncryptionAlgorithm
- OutputFormat
- UseOAEP
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:
When a valid source is found the search stops. The order in which the output properties are checked is as follows:
- OutputFile
- OutputMessage: 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
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 class 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 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:
When a valid source is found the search stops. The order in which the output properties are checked is as follows:
- OutputFile
- OutputMessage: 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 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:
- Certificates (Required)
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:
When a valid source is found the search stops. The order in which the output properties are checked is as follows:
- OutputFile
- OutputMessage: 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.
- certCount | The number of records in the Cert arrays. |
- certEncoded:(int)certIndex | The certificate (PEM/base64 encoded). |
- certStore:(int)certIndex | The name of the certificate store for the client certificate. |
- certStorePassword:(int)certIndex | 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. |
- certStoreType:(int)certIndex | The type of certificate store for this certificate. |
- certSubject:(int)certIndex | The subject of the certificate used for client authentication. |
- detachedSignature | Specifies whether to include a detached signature when signing a message. |
- detachedSignatureData | The detached signature. |
- enableCompression | Specifies whether to compress the message. |
- encryptionAlgorithm | The algorithm used for encryption. |
- includeCertificates | Specifies whether to include the signer's certificate with the signed message. |
- inputFile | The file to process. |
- inputMessage | The message to process. |
- outputFile | The output file. |
- outputFormat | Specifies the output format. |
- outputMessage | The output message after processing. |
- recipientCertCount | The number of records in the RecipientCert arrays. |
- recipientCertEncoded:(int)recipientCertIndex | The certificate (PEM/base64 encoded). |
- recipientCertStore:(int)recipientCertIndex | The name of the certificate store for the client certificate. |
- recipientCertStorePassword:(int)recipientCertIndex | 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. |
- recipientCertStoreType:(int)recipientCertIndex | The type of certificate store for this certificate. |
- recipientCertSubject:(int)recipientCertIndex | The subject of the certificate used for client authentication. |
- signatureHashAlgorithm | The signature hash algorithm used during signing. |
- signerCertCount | The number of records in the SignerCert arrays. |
- signerCertEncoded:(int)signerCertIndex | The certificate (PEM/base64 encoded). |
- signerCertStore:(int)signerCertIndex | The name of the certificate store for the client certificate. |
- signerCertStorePassword:(int)signerCertIndex | 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. |
- signerCertStoreType:(int)signerCertIndex | The type of certificate store for this certificate. |
- signerCertSubject:(int)signerCertIndex | The subject of the certificate used for client authentication. |
- useOAEP | Whether to use Optimal Asymmetric Encryption Padding (OAEP). |
- usePSS | 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.
- addCertificate | Used to add certificates for signing. |
- addRecipientCert | Used to add recipient certificates used to encrypt messages. |
- config | Sets or retrieves a configuration setting. |
- decrypt | Decrypts the current message. |
- decryptAndVerifySignature | Decrypts and verifies the signature of the current message. |
- encrypt | Encrypts the current message. |
- getRecipientInfo | Gets the recipient certificate information for an encrypted message. |
- getSignerCertInfo | Gets the signature information for an signed message. |
- reset | Resets the class properties. |
- sign | Signs the current message. |
- signAndEncrypt | Signs and encrypts the current message. |
- verifySignature | 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.
- onError | Information about errors during data delivery. |
- onLog | Fires with log information during processing. |
- onRecipientInfo | Fired for each recipient certificate of the encrypted message. |
- onSignerCertInfo | 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. |