Skip to main content
Skip table of contents

S/MIME

Using an S/Notify release before version 4.0 (or before Bitbucket 2.0)? Then please refer to Earlier Versions for the appropriate documentation.

This page provides general information about the S/MIME support in S/Notify

S/MIME Certificate Retrieval

S/Notify offers five different ways to retrieve S/MIME certificates for users:

  • Key store file: S/MIME certificates can be provided in a key store file

  • User directory: an LDAP configured as a user directory can be used to provide S/MIME certificates

  • External LDAP: any additional LDAP server can be used to search for S/MIME certificates

  • Incoming email: S/MIME certificates can be extracted from users' incoming signed email

  • User upload: users can upload their public S/MIME certificates to their user profiles

S/Notify can be configured to use one of these options or any combination of them.

The priority in which certificates from these sources are used:

  1. User upload (skipped when user is inactive)

  2. Incoming email

  3. Key store file

  4. User directory

  5. External LDAP

User directory

Probably, the most convenient way is to store public user certificates in the same LDAP that is configured as the user directory and let S/Notify retrieve them from there.

The user's S/MIME certificate can be stored in the userSMIMECertificate or the userCertificate attribute. Please see below section LDAP userSMIMECertificate vs. userCertificate attribute for details.

External LDAP

If you have outside users (who are not in the Jira user directory), it may be necessary or useful to retrieve their S/MIME certificates from an additional LDAP. 

The user's S/MIME certificate can be stored in the userSMIMECertificate or the userCertificate attribute. Please see below section LDAP userSMIMECertificate vs. userCertificate attribute for details.

LDAP userSMIMECertificate vs. userCertificate attribute

There are two LDAP attributes that can hold the user's S/MIME certificate in slightly different ways: userSMIMECertificate and userCertificate. If available, the userSMIMECertificate attribute is preferred over the userCertificate attribute, in accordance with RFC 2798.

Attribute userSMIMECertificate is expected to be in PKCS#7 SignedData message format according to RFC 2315: PKCS #7: Cryptographic Message Syntax. As such, it can provide not only the user's certificate, but also all other certificates in the certificate chain. It may also include preferences regarding the encryption algorithms.

Attribute userCertificate is expected to hold a single certificate in DER binary format according to https://datatracker.ietf.org/doc/html/rfc4523#section-2.1. 

Key store file

If you do not have an LDAP server, or if you must encrypt for users who are not listed in your LDAP, the certificates required to S/MIME encrypt notification emails can be provided by using a central keystore file. You can use the same keystore for both, S/Notify for Jira and S/Notify for Confluence. 

S/Notify currently supports the following two formats:

  • PKCS#7 

  • BouncyCastle

PCKS#7 Bundle (P7B)

This is a common format for exporting and transmitting public certificates. It can hold multiple certificates and is therefore often referred to as a p7 bundle – hence the commonly used file suffix p7b. It is defined in RFC 2315, originally meant for cryptographic messaging. 

Because PKCS#7 bundles can hold only public certificates, no encryption or access restrictions are required, hence no password is required.

Any software tool managing certificates should be able to export public certificates in PKCS#7 format out of the box. Therefore, it is very easy to create a PKCS#7 key store, and for a smaller number of certificates, we recommend that you just perform a PKCS#7 export from your current certificate store.

Note that S/Notify expects the file to be in DER encoded (binary) format. While the Certificate Manager built into MS Windows exports PKCS#7 bundles in DER encoded format, openssl crl2pkcs7 creates PEM encoded files by default, so it should be used with option -outform der to create a keystore file for S/Notify.

BouncyCastle Keystore (BKS)

BouncyCastle key stores (BKS) are similar to Java keystores (JKS), but can be used without password protection if they hold only public certificates. They can be created 

  • from an existing Java keystore

  • from a PKCS#12 keystore

  • (with some extra work) from DER or PEM encoded certificate files

BouncyCastle key stores are created with the command line tool keytool which is provided with Java.

For details about the BouncyCastle keystores, please refer to section 6.4 of the BouncyCastle specifications.

Create from an existing Java keystore

If you have an existing Java keystore, it can be converted to a BouncyCastle keystore. Java keystore files usually have the file suffix jks.

Example
BASH 
keytool -importkeystore -destkeystore "<bcKeystore.bks>" -storetype BKS \\
        -srckeystore "<javaKeystore.jks>" -srcstoretype JKS \\
        -provider net.savignano.thirdparty.org.bouncycastle.jce.provider.BouncyCastleProvider \\
        -providerpath "<PathToSNotifyMailerJar>"
Parameter explanations

  • Replace <bcKeystore.bks> by the path and filename of the BouncyCastle keystore you want to create

  • Replace <javaKeystore.bks> by the path and filename of the Java keystore you want to convert from

  • Replace <PathToSNotifyMailerJar> by the path and filename of the S/Notify mailer jar.

The BouncyCastle provider is contained in the S/Notify mailer library jar which must be downloaded as in explained in Step 2: Download and install the S/Notify library component of the installation instructions.

Create from a PKCS#12 keystore (p12)

You can use a PKCS#12 keystore to convert it to a BouncyCastle keystore. PKCS#12 – sometimes referred to as just PKCS12 – also is a common export format. PKCS#12 keystore files usually have a file suffix p12 or, typically on Windows, pfx.

Example
BASH 
keytool -importkeystore -destkeystore "<bcKeystore.bks>" -storetype BKS \\
        -srckeystore "<pkcs12keystore.p12>" -srcstoretype PKCS12 \\
        -provider net.savignano.thirdparty.org.bouncycastle.jce.provider.BouncyCastleProvider \\
        -providerpath "<PathToSNotifyMailerJar>"
Parameter explanations

  • Replace <bcKeystore.bks> by the path and filename of the BouncyCastle keystore you want to create

  • Replace <javaKeystore.bks> by the path and filename of the Java keystore you want to convert from

  • Replace <PathToSNotifyMailerJar> by the path and filename of the S/Notify mailer jar.

The BouncyCastle provider is contained in the S/Notify mailer library jar which must be downloaded as in explained in Step 2: Download and install the S/Notify library component of the installation instructions.

Create from DER or PEM encoded certificates

If you do not have an existing Java keystore, you can create a BouncyCastle keystore and import DER or PEM certificates into it.

Example

keytool -importcert -file "<certificate.cer>" -alias "<UniqueAlias>" -keystore "<bcKeystore.bks>" -storetype BKS -provider net.savignano.thirdparty.org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath "<PathToSNotifyMailerJar>"

Parameter explanations

  • Replace <certificate.cer> by name the path and filename of the certificate to be imported into the keystore - either DER or PEM format works

  • Replace <UniqueAlias> by a unique ID which will be required if the entry ever needs to be updated or removed - hint: you may use the userid or email address for this

  • Replace <bcKeystore.bks> by the path and filename of the BouncyCastle keystore you want to create

  • Replace <PathToSNotifyMailerJar> by the path and filename of the S/Notify mailer jar.

Password

A password will be requested. When the keystore is initially created, this password will be stored with the keystore, and the identical password will be requested for all subsequent imports.

You can add the following parameter to the above command to provide the password: 

CODE 
-storepass <password>

The password is not required to retrieve public certificates from the keystore. Therefore, the password is not requested when configuring a keystore for S/Notify.

Trust confirmation

When importing new certificates, you will be asked, if you want to trust the certificate. Of course, you should answer that you do. Alternatively, you can switch the confirmation off by adding this parameter to the command:

CODE 
-noprompt
Unix/Linux script

For your convenience, we provide the following script which allows you to import multiple certificates from a directory in one pass. The keystore aliases are derived from the filenames excluding the file suffix.

bksimport.sh
BASH 
#!/bin/bash

# Import all certificates in a folder into a BouncyCastle keystore

# Usage example:
#
#   bksimport.sh certificate-path snotify-keystore.bks /opt/atlassian/jira/atlassian-jira/WEB-INF/lib/net.savignano.s-notify.jira.mailer-1.2.1.jar


if [ $# != 3 ]; then
        echo "Usage: $0 cert-path keystore.bks /path/to/net.savignano.s-notify.jira.mailer-xxx.jar"
        exit 1
fi

CERTDIR=$1
KEYSTORE=$2
BCPROV=$3

read -p "Enter keystore password" -s kspw

printf "\n\nCreating keystore ${KEYSTORE} from all PEM files in ${CERTDIR}\n"

for cert in $1/*.pem
do
	name="${cert##*/}"
    name="${name%.*}"

    printf "${cert} - "

    keytool -importcert -file "${cert}" -alias "${name}" -keystore "${KEYSTORE}" -storetype BKS -provider net.savignano.thirdparty.org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath "${BCPROV}" -noprompt -storepass "${kspw}"

done

Use, copy, modify, re-share as you like.

Check certificates in a keystore

This lists all certificates in the keystore, including details about each certificate:

keytool -list -v -keystore "<bcKeystore.bks>" -storetype BKS  -provider net.savignano.thirdparty.org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath "<PathToSNotifyMailerJar>"

Certificate Classes

S/MIME certificates are sometimes assigned different classes, which are intended to represent the grade of verification of the certificate owner. For example, for a “class 1” S/MIME certificate, only the email address has been verified, while in a “class 2” S/MIME certificate, also the owner’s name and the company or organization has been verified by the issuer. For “class 3”, specific documents are required for the verification , and “class 4” requests a verification in person. Certificate classes are not part of the standard, and were introduced by certification authorities, perhaps for more economical reasons.

In practical use, these classes do not make a difference. Even more, the class is either not part of the certificate, or only in a proprietary way that depends on the issuer. The only differentiation could be made between class 1 and the other classes, but the question remains why “class 1” certificates should be rejected. Therefore, S/Notify does not make a difference between these of S/MIME certificate classes.

Encryption Ciphers

Content Encryption

Algorithms

S/Notify supports all ciphers required by S/MIME 4.0 (and quite some more, but they tend not to play any role in real life).

Selection

S/Notify tries to use AES-256 for S/MIME encryption. If Java Cryptography Support is limited, S/Notify falls back to using AES-128. 

Client preferences encoded in PKCS#7 encoded messages (p7m) are not evaluated, because most email clients do not provide them anyway for good reasons.

Key Encryption

Algorithms

The following asymmetric ciphers are supported:

  • RSA

  • DSA

  • ECDSA

  • EdDSA

  • ECDH (Curve25519)

  • GOST3410

  • DSTU4145

  • ElGamal

  • NIST P-256/386/521

  • Brainpool P-256/386/512

  • secp256k1

Digest Algorithm

The digest algorithm used when signing outgoing emails is SHA-256.

The digest algorithm is also sometimes referred to as hash algorithm. In the S/MIME specification documents, it is called message integrity check algorithm, hence the abbreviation micalg in the message header.







JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close