IPWorks S/MIME 2020 Python Edition

Questions / Feedback?

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:

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

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.

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_encodedThe certificate (PEM/base64 encoded).
cert_storeThe name of the certificate store for the client certificate.
cert_store_passwordIf 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_typeThe type of certificate store for this certificate.
cert_subjectThe subject of the certificate used for client authentication.
detached_signatureSpecifies whether to include a detached signature when signing a message.
encrypting_algorithmTextual description of the encrypting algorithm.
include_certificateSpecifies whether to include the signer's certificate with the signed message.
include_chainSpecifies whether to include the signer's certificate chain with the signed message.
include_headersTells the class whether to include the headers when encoding the message.
input_fileThe file to process.
input_messageThe message to process.
input_message_header_countThe number of records in the InputMessageHeader arrays.
input_message_header_fieldThis property contains the name of the HTTP header (same case as it is delivered).
input_message_header_valueThis property contains the header contents.
input_message_headers_stringString version of headers from the SMIME message.
internal_headersThe headers of the MIME entity inside the encrypted or signed message.
message_encryptedWhether or not the current message is encrypted.
message_signedWhether or not the current message is signed.
output_fileThe output file.
output_messageThe output message after processing.
output_message_header_countThe number of records in the OutputMessageHeader arrays.
output_message_header_fieldThis property contains the name of the HTTP header (same case as it is delivered).
output_message_header_valueThis property contains the header contents.
output_message_headers_stringString version of headers from the SMIME message.
overwriteIndicates whether or not the class should overwrite files.
recipient_cert_countThe number of records in the RecipientCert arrays.
recipient_cert_encodedThe certificate (PEM/base64 encoded).
recipient_cert_storeThe name of the certificate store for the client certificate.
recipient_cert_store_passwordIf 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_typeThe type of certificate store for this certificate.
recipient_cert_subjectThe subject of the certificate used for client authentication.
signer_cert_encodedThe certificate (PEM/base64 encoded).
signer_cert_issuerThe issuer of the certificate.
signer_cert_serial_numberThe serial number of the certificate encoded as a string.
signer_cert_storeThe name of the certificate store for the client certificate.
signer_cert_store_passwordIf 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_typeThe type of certificate store for this certificate.
signer_cert_subjectThe subject of the certificate used for client authentication.
signer_cert_chain_countThe number of records in the SignerCertChain arrays.
signer_cert_chain_encodedThe certificate (PEM/base64 encoded).
signing_algorithmTextual description of the signature hash algorithm.
use_oaepWhether to use Optimal Asymmetric Encryption Padding (OAEP).
use_pssWhether 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_recipient_certUsed to add recipient certificates used to encrypt messages.
configSets or retrieves a configuration setting.
decryptDecrypts the current Message .
decrypt_and_verify_signatureDecrypts and verifies the signature of the current message.
encryptEncrypts the message.
get_recipient_infoGets the recipient infos for an encrypted message.
get_signer_cert_infoGets the signature information for an signed message.
resetResets the class properties.
signSigns the current message.
sign_and_encryptSigns and encrypts the current message.
verify_signatureVerifies 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_errorInformation about errors during data delivery.
on_recipient_infoFired for each recipient certificate of the encrypted message.
on_signer_cert_infoFired 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.

ApplyB64EncodingInstructs the class to base64 encode the message when signing or encrypting.
CSPThe Cryptographic Service Provider.
GenerateSignatureTimestampWhether to generate timestamps in signatures.
IncludeHeadersTells the class whether to include the headers when encoding the message.
IncludeInternalHeadersTells the class 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.
InputMessageEncryptedWhether or not the input message is encrypted.
InputMessageSignedWhether or not the input message is signed.
OAEPMGF1HashAlgorithmThe MGF1 hash algorithm used with OAEP.
OAEPParamsThe hex encoded OAEP parameters.
OAEPRSAHashAlgorithmThe RSA hash algorithm used with OAEP.
ParseInternalHeadersTells the class whether or not to parse the message part headers when decrypting a message.
RecipientCertUsed to specify the public certificate when using a PEM key to decrypt.
RecipientCertFileUsed to specify the public certificate file when using a PEM key to decrypt.
RecipientInfoTypeThe type of signer information to include 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.
UseCryptoAPIWhether to use the Microsoft Crypto API for cryptographic message generation.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPITells the class whether or not to use the system security libraries or an internal implementation.

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