S/MIME

Usage

The S/MIME module enables you to encrypt, decrypt or sign MIME formatted input messages as well as check their signatures.

RSA PKCS 1.5, PSS, and OAEP as well as EC and RSA public key length of 2048 bits are supported.

Generating Keys and Certificates in the S/MIME Utility

For encryption, you need keys which you can generate using the Java keytool. You can enter the algorithm to be used while generating the key.

For information about calling keytool, refer to Configuring SSL Connections and Server Authentication.

Example: Generating a key

keytool \
  -genkey \
  -dname "O=Virtimo, C=de" \
  -validity 365 \
  -keystore smime.keystore \
  -keypass inubit \
  -storepass inubit \
  -alias inubit \
  -keyalg RSA

Example: Generating a certificate

keytool \
  -export \
  -keystore smime.keystore \
  -alias inubit \
  -file smime.cer

Module Variables of the S/MIME Utility

The following table contains variables that are set by the S/MIME Utility based on the input message:

Module variable Value

Module variable	Value
`SMIMEEncryptionAlgorithm`	Content encryption algorithm used to encrypt the message content
`SMIMEKeyEncryptionAlgorithm`	Key encryption algorithm used to exchange symmetric keys necessary to encrypt the content
`SMIMEisEncyrpted`	Information whether the message is encrypted (`SMIMEisEncyrpted=true`) or not (`SMIMEisEncyrpted=false`)
`SMIMEHashingAlgorithm`	Signature hash algorithm used for message
`SMIMESignatureAlgorithm`	Signature algorithm used for message
`SMIMEisSigned`	Information whether the message is signed (`SMIMEisSigned=true`) or not (`SMIMEisSigned=false`)
`SMIMEVerifyCertData`	Base64-encoded certificate (DER) used to verify the signature. Only set if the Use message-embedded certificate option is active.
`SMIMEAttachmentCount`	Number of attachments transferred to the output after the attachment validation. Only set if an attachment type filter or a maximum number of attachments is active.

SMIMEEncryptionAlgorithm

Content encryption algorithm used to encrypt the message content

SMIMEKeyEncryptionAlgorithm

Key encryption algorithm used to exchange symmetric keys necessary to encrypt the content

SMIMEisEncyrpted

Information whether the message is encrypted (SMIMEisEncyrpted=true) or not (SMIMEisEncyrpted=false)

SMIMEHashingAlgorithm

Signature hash algorithm used for message

SMIMESignatureAlgorithm

Signature algorithm used for message

SMIMEisSigned

Information whether the message is signed (SMIMEisSigned=true) or not (SMIMEisSigned=false)

SMIMEVerifyCertData

Base64-encoded certificate (DER) used to verify the signature. Only set if the Use message-embedded certificate option is active.

SMIMEAttachmentCount

Number of attachments transferred to the output after the attachment validation. Only set if an attachment type filter or a maximum number of attachments is active.

Dialog Description in the S/MIME Utility

Dialog S/MIME Configuration

MIME encryption

Output messages are S/MIME encrypted. To this end, the sender must know the recipient’s public key. To do so, you as sender need to have the public key of the recipient. You store this key in the next dialog.
MIME decryption

Input messages are decrypted by using the recipient’s private key. You store this key in the next dialog.
Sign MIME

Signs the output messages by adding an encrypted checksum. To do so, you need a private key. You store this key in the next dialog. The recipient must have the sender’s public key to verify the signature.
Check MIME signature / Extract signed data

Allows verifying the correctness of the signature in the input message by comparing the signature with the sender’s public key. You store this key in the next dialog. Allows extracting the message without prior signature check as well as copying the message headers.

Dialog S/MIME Encryption

Displayed when using the MIME encryption option.

This dialog offers the following options:

Encryption algorithm

Select the encryption algorithm from the drop-down list.

To set the encryption algorithm using module properties, set the variable smime.encryption.algo to the required algorithm name.

Key encryption algorithm

If no key encryption algorithm is selected, the key encryption algorithm configured in the certificate is considered.

You can also use the smime.key.encryption.algo module property to set the key encryption algorithm using the variables mapping. If this module property is set, it overrides the configured value set using this dialog.

Hashing Algorithm

If you have selected the RSAES-OAEP key encryption algorithm, you can choose a hashing algorithm from the drop-down list.

SHA-1 is set by default.

You can set/override the hashing algorithm by using the smime.rsaoaep.hash.algo module property.
Key wrap algorithm

If you have selected the ECDH key encryption algorithm, you must select a key wrap algorithm from the drop-down list. This algorithm encrypts and safeguards cryptographic keys during storage or transmission using another key, such as AES Key Wrap.

AES128_WRAP is set by default.
Key derivation function

If you have selected the ECDH key encryption algorithm, you must select a key derivation function from the drop-down list. This function generates cryptographic keys from inputs and is utilised in key generation and password-based key derivation, such as KDF.

ECDH_SHA256KDF is set by default.
Add recipient’s public certificate

Click Add to add the certificate file.
Certificate data

This field displays an already added certificate.

Dialog S/MIME Decryption

Displayed when using the MIME decryption option.

In INUBIT, Bouncy Castle is used internally to automatically decrypt messages with the appropriate decryption algorithm.

Add private key

Click Add to add the private key in JKS format.

Public key data

This field displays already added private keys.

Dialog S/MIME Sign message

Displayed when using the Sign MIME option.

This dialog offers the following options:

Hashing algorithm

Choose the hashing algorithm from the drop-down list.

Signature algorithm

If no signature algorithm is selected, the signature algorithm configured in the certificate is considered.

You can also use the smime.signature.algo module property to set the signature algorithm using the variables mapping. If this module property is set, it overrides the configured value set using this dialog.

Add private key

Click Add to add the private key in JKS format.
Public key data

This field displays an already added private key.

Dialog Check S/MIME Signature / Extract signed data

Displayed when using the Check MIME signature / Extract signed data option. In this dialog, you define whether the signature is verified, which data is transferred, and which certificate is used for verification.

Activate signature verification

If activated, the correctness of the signatures in the input message is checked. This is done by validating the signatures against the public key of the sender. If the verification fails, the module aborts with an error message.

Extract signed data

If activated, the signed user data is extracted from the message and only this data is transferred. If Activate signature verification is also selected, the user data is only extracted after successful verification. Content outside the signed part of the message is not transferred.

If this option is deactivated, the input message is transferred unchanged after successful verification.

Copy additional headers

If activated, the message headers are copied in addition. This option is only available if Extract signed data is selected.

Attachment validation

The attachment validation defines which attachments from the signed part of a message are transferred and how many attachments a message may contain. These options are only available if Extract signed data is selected.

Any message part that has a file name or is marked as an attachment (Content-Disposition: attachment) is considered an attachment.

Allowed attachment type: Content type of the attachments transferred to the output, for example application/pdf. You can select a value from the list or enter a custom value. Separate multiple types with commas, for example application/pdf, application/xml. A type also matches if the content type of an attachment starts with it, for example image/ matches all image formats.

Attachments that do not match any of the types are removed from the output. If no attachment matches the specified types, the module aborts with an error message.

The default value is */*, which transfers all attachment types.
Max. allowed attachments: Maximum number of attachments a message may contain. Only attachments that match the allowed attachment type are counted. If the message contains more attachments, the module aborts with an error message.
Unlimited: If activated, the number of attachments is not limited and the Max. allowed attachments field is deactivated. This option is activated by default.

The number of transferred attachments is provided in the SMIMEAttachmentCount module variable. The original MIME headers, the Message-ID, and the MIME boundaries of the message are preserved.

You can also configure the attachment validation using the smime.attachments.type.filter, smime.attachments.max, and smime.unlimited.attachments module properties.

Signer’s public certificate

In this area, you define which certificate is used to verify the signature. The following options are available:

Use static certificate data

The signature is verified with a certificate that you store in the module. This option is selected by default for new modules.

Click Add to add the certificate of the signer. Single X.509 certificates in PEM or DER format, Java KeyStores (JKS), and PKCS#7 files (.p7b, .p7c, .p7s) are supported. If a PKCS#7 file contains a certificate chain, the signer’s certificate is selected automatically. An already added certificate will be overwritten.

The Certificate data field displays the added certificate.

You can also provide the certificate as a Base64-encoded value using the smime.certificate.data module property. Single certificates and PKCS#7 structures with certificate chains are supported there as well.

Select from Credentials Manager

The signature is verified with a certificate stored in the Credentials Manager. Select the alias of the certificate.

Use message-embedded certificate

The signature is verified with the certificate that the sender includes in the signed message. You do not need to store a certificate in the module.

The certificate used is provided in the SMIMEVerifyCertData module variable.

With this option, the embedded certificate is not checked against a trusted certificate or certificate authority. A successful verification only confirms that the message has not been modified after signing, but not the identity of the sender. Check the certificate from SMIMEVerifyCertData in your workflow if you need to authenticate the sender.

Keywords: