SMIME Component
Properties Methods Events Configuration Settings Errors
The SMIME component implements the S/MIME standard for encryption and decryption with public key cryptography and X.509 digital certificates.
Syntax
ipworksencrypt.Smime
Remarks
The SMIME component implements the S/MIME V3 standard for encryption and decryption using Public Key Cryptography Standards (PKCS). In addition the component can be used to both generate and verify RSA digital signatures. Using this component for decrypting or signing requires a valid digital certificate with a private key.
Before performing an operation the input and output values should be specified.
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:
- SetOutputStream
- OutputFile
- OutputMessage: The output data is written to this property if no other destination is specified.
When using streams you may need to additionally set CloseInputStreamAfterProcessing or CloseOutputStreamAfterProcessing.
The headers of the input message (if any) will be read from InputMessageHeaders or InputMessageHeadersString.
The headers of the resulting message will be available in the OutputMessageHeaders and OutputMessageHeadersString properties.
Signing
To sign the current data included in the input message with a certificate, the Certificate property must be set to a valid Certificate object for the signing certificate. The IncludeCertificate and DetachedSignature properties allow you to specify additional details about the signing process. By setting IncludeCertificate to true, digital certificates can be encoded and included in message signature when signing the document. Including a certificate is the preferred method of building signed messages. In addition the SMIME component can also generate PKCS #7 formatted detached digital signatures and envelopes by specifying DetachedSignature.
Encrypting
To encrypt a message with the component in a PKCS envelope, you must first specify the Certificate for each recipient in the RecipientCerts collection to encrypt the message with. You can easily add these with the AddRecipientCert method. Once you have done this you can call the Encrypt method to encrypt the message with the recipient certificates.
In addition, the component allows you to sign and encrypt simultaneously with the SignAndEncrypt method. You must set all of the properties needed for both Sign and Encrypt
The result of the encrypted or signed data will be replaced in the OutputMessage property and the OutputMessageHeaders property will be filled with the appropriate mime headers if applicable.
Decrypting
Decrypting PKCS envelopes is handled with the Decrypt method. When this method is called, the component will attempt to find an appropriate certificate in the Certificate property that matches the encrypting certificate. If it cannot find an appropriate certificate an exception will be thrown and the message will not be decrypted.
Verifying Signatures
In addition the SMIME component can be used to verify signatures included in signed messages or documents. After specifying the input, VerifySignature can then be used to verify the signature. If the message does not have a certificate attached more then likely an exception will be thrown and the component will not be able to verify the signature. If VerifySignature is successful, the SignerCert and SignerCertChain properties will be filled with the certificate information of the message signer. This information can be used to verify the signing certificates.
Similar to SignAndEncrypt, DecryptAndVerifySignature can be used to both decrypt and verify the message in Message.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
| Certificate | The current selected certificate. |
| DetachedSignature | Specifies whether to include a detached signature when signing a message. |
| EncryptingAlgorithm | Textual description of the encrypting algorithm. |
| IncludeCertificate | Specifies whether to include the signer's certificate with the signed message. |
| IncludeChain | Specifies whether to include the signer's certificate chain with the signed message. |
| IncludeHeaders | Tells the component whether to include the headers when encoding the message. |
| InputFile | The file to process. |
| InputMessage | The message to process. |
| InputMessageHeaders | Collection of headers from the SMIME message. |
| InputMessageHeadersString | String version of headers from the SMIME message. |
| InternalHeaders | The headers of the MIME entity inside the encrypted or signed message. |
| MessageEncrypted | Whether or not the current message is encrypted. |
| MessageSigned | Whether or not the current message is signed. |
| OutputFile | The output file. |
| OutputMessage | The output message after processing. |
| OutputMessageHeaders | Collection of headers from the SMIME message. |
| OutputMessageHeadersString | String version of headers from the SMIME message. |
| Overwrite | Indicates whether or not the component should overwrite files. |
| RecipientCerts | The collection of recipient certificates of the message. |
| SignerCert | Contains the certificate of the message signer. |
| SignerCertChain | The certificate chain of the signing certificate. |
| SigningAlgorithm | Textual description of the signature hash algorithm. |
| 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 component with short descriptions. Click on the links for further details.
| 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 message. |
| GetRecipientInfo | Gets the recipient infos for an encrypted message. |
| GetSignerCertInfo | Gets the signature information for an signed message. |
| Reset | Resets the component properties. |
| SetInputStream | Sets the stream from which the component will read data to encode or decode. |
| SetOutputStream | The stream to which the component will write the fully encoded or decoded S/MIME data. |
| 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 component with short descriptions. Click on the links for further details.
| Error | Information about errors during data delivery. |
| RecipientInfo | Fired for each recipient certificate of the encrypted message. |
| SignerCertInfo | Fired 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.
| ApplyB64Encoding | Instructs the component to base64 encode the message when signing or encrypting. |
| CloseInputStreamAfterProcess | Determines whether or not the input stream is closed after processing. |
| CloseOutputStreamAfterProcess | Determines whether or not the output stream is closed after processing. |
| CSP | The Cryptographic Service Provider. |
| GenerateSignatureTimestamp | Whether to generate timestamps in signatures. |
| IncludeHeaders | Tells the component whether to include the headers when encoding the message. |
| IncludeInternalHeaders | Tells the component 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. |
| InputMessageEncrypted | Whether or not the input message is encrypted. |
| InputMessageSigned | Whether or not the input message is signed. |
| OAEPMGF1HashAlgorithm | The MGF1 hash algorithm used with OAEP. |
| OAEPParams | The hex encoded OAEP parameters. |
| OAEPRSAHashAlgorithm | The RSA hash algorithm used with OAEP. |
| ParseInternalHeaders | Tells the component whether or not to parse the message part headers when decrypting a message. |
| RecipientCert | Used to specify the public certificate when using a PEM key to decrypt. |
| RecipientCertFile | Used to specify the public certificate file when using a PEM key to decrypt. |
| RecipientInfoType | The type of signer information to include 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. |
| UseCryptoAPI | Whether to use the Microsoft Crypto API for cryptographic message generation. |
| VerifyCertChain | Whether to verify the certificate chain of the certificate used to sign the message. |
| BuildInfo | Information about the product's build. |
| GUIAvailable | Tells the component whether or not a message loop is available for processing events. |
| LicenseInfo | Information about the current license. |
| UseDaemonThreads | Whether threads created by the component are daemon threads. |
| UseInternalSecurityAPI | Tells the component whether or not to use the system security libraries or an internal implementation. |