SMIME Class

Properties   Methods   Events   Configuration Settings   Errors  

The SMIME class implements the S/MIME standard for encryption and decryption with public key cryptography and X.509 digital certificates.

Syntax

class ipworkssmime.SMIME

Remarks

The SMIME class implements the S/MIME V3 standard for encryption and decryption using Public Key Cryptography Standards (PKCS). In addition the class can be used to both generate and verify RSA digital signatures. Using this class 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 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.

The headers of the input message (if any) will be read from input_message_headers or input_message_headers_string.

The headers of the resulting message will be available in the output_message_headers and output_message_headers_string 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 include_certificate and detached_signature properties allow you to specify additional details about the signing process. By setting include_certificate 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 class can also generate PKCS #7 formatted detached digital signatures and envelopes by specifying detached_signature.

Encrypting

To encrypt a message with the class in a PKCS envelope, you must first specify the Certificate for each recipient in the recipient_certs properties to encrypt the message with. You can easily add these with the add_recipient_cert method. Once you have done this you can call the encrypt method to encrypt the message with the recipient certificates.

In addition, the class allows you to sign and encrypt simultaneously with the sign_and_encrypt 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 output_message property and the output_message_headers 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 class 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 class can be used to verify signatures included in signed messages or documents. After specifying the input, verify_signature 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 class will not be able to verify the signature. If verify_signature is successful, the signer_cert and signer_cert_chain properties will be filled with the certificate information of the message signer. This information can be used to verify the signing certificates.

Similar to sign_and_encrypt, decrypt_and_verify_signature can be used to both decrypt and verify the message in message.