(3.x) User Key Management - S/Notify for Jira

Orange colored text describes functional differences in previous 3.x releases

Under this configuration entry, the public PGP keys or S/MIME certificates for Jira users (including customers in Jira Service Desk) are managed. They are used for the encryption of outgoing emails.

For this, you will find the following configuration options:

Global User Key Management

This section has two tabs each displaying one of the two different encryption methods.

We recommend that you always click Verify Settings after having made changes here. 

S/MIME

Key store file

In this section of the S/Notify configuration settings, you can optionally provide a global key store containing the certificates to be used for S/MIME email encryption.

Note that, due to the nature of asymmetric encryption, S/Notify requires only public certificate keys from the key store. As a consequence, a password is not required for access to the key store.

Key store format

The key store file must be in either of the following two formats:

• PKCS#7 (recommended)
  This format is a common format used to export and transmit 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. Note that the file needs to be in DER encoded (binary) format.
• BouncyCastle 
  This format is usually represented by a file suffix of bks. It is supported mainly for backward compatibility reasons. The key store must be a BKS type BouncyCastle key store. For details on how to create such a key store, please refer to (3.x) S/MIME. 

Prior to version 3.1, the PKCS#7 format was not supported.

Key store location

Provide path and file name of the certificate key store, as seen from the server your Jira instance runs on. 

User directory

Prior to version 3.5, this section was named LDAP server. It was renamed to avoid confusion with external LDAP servers.

If enabled, S/Notify will use the LDAP server from the Jira user directory the user is associated with, if applicable. 

This setting requires that an LDAP server is used as a Jira user directory, and that the user is found in this directory. S/Notify will then query the user's S/MIME certificate from the LDAP server in the following order and format:

Note that if both, key store and LDAP server are used, certificates found in the key store will take precedence over those on the LDAP server.

External LDAP server

S/Notify can optionally search for S/MIME certificates on an external LDAP server (outside Jira's configuration). 

Personal Identifiable Information

Note that, in order to retrieve a user's S/MIME certificate, their email address needs to be sent to the server. If the LDAP server is outside your company's own infrastructure, you may be required to inform your users about this use of their email address, depending on your and/or your users jurisdiction. Legislation around personal identifiable information (PII) varies across different jurisdictions (GDPR, HIPAA, PCI etc.), so please check what applies in your case.

Hostname

The domain of the LDAP server, excluding the protocol part.

Port / SSL

The port served by the LDAP server. Usually 389 or 636 for SSL enabled connections (recommended). 

User / password

Optional. Only if the server requires authentication.

Base DN

Most LDAP servers require to provide the Base DN of the root node to search from. Optionally, any additional DN can be prepended to limit the search scope (and thus improve speed).

Filter

Optionally, a filter can be provided to limit the search to specific objects. The filter will be added to the default filter that is used to search for objects with the email address being processed (mail=emailAddress).

Prior to version 3.5, external LDAP servers were not supported.

Incoming email

If checked, user certificates included in an S/MIME signature of incoming emails are extracted and stored as the user's public certificate for encryption of all emails to this user. This option may be used as a simple way for users to provide their S/MIME certificate. Note that such certificates will override certificates in key stores or LDAP servers.

If you have configured Jira to create new users from incoming emails (or new customers in Jira Service Management), then the user may not yet exist during incoming email processing. In this case, the extracted certificate will be saved in an intermediate storage, and then added to the user after it has been created by Jira.

Prior to version 3.2, certificate extraction from incoming email was not available.

Prior to version 3.5, deferred certificate storage for new users was not available.

User override

If checked, Jira users are allowed to upload their own S/MIME certificates from their user profile page. If a suitable certificate is provided in both, the global key store and the user profile, the one from the user profile will be used.

Jira Service Desk customers

Only if you run Jira Service Desk, another checkbox will display to separately allow or disallow service desk customers to upload their own S/MIME certificate from their profile page.

Prior to version 3.3, it was not possible for service desk customers to upload their own S/MIME certificates.

PGP

Key store file

In this section of the S/Notify configuration settings, you can optionally provide a global key store containing the keys to be used for PGP email encryption.

Note that, due to the nature of asymmetric encryption, S/Notify requires only public keys from the key store. As a consequence, a password is not required for access to the key store.

Key store format

The key store file must be in either of the following two formats:

• ASCII-Armored
  This format is a common format used to export and transmit public keys. It is, as the name implies, encoded fully in ASCII. Usual file endings are: asc, txt
• PGP Binary
  PGP binary file format. Usual file endings are: pgp, gpg, pkr

Keybox format

Note that the new keybox format (kbx) is not currently supported. If your GPG installation uses the keybox format, you must export it in one of the above formats in order to use it as a key store for S/Notify.

Key store location

Provide path and file name of the certificate key store, as seen from the server your Jira instance runs on. 

Key server

In this section of the S/Notify configuration settings, you can provide an URL to a PGP key server that will be searched for PGP keys to encrypt with.

Personal Identifiable Information

Note that, in order to retrieve a user's PGP key, their email address needs to be sent to the server. If the key server is outside your company's own infrastructure, you may be required to inform your users about this use of their email address, depending on your and/or your users jurisdiction. Legislation around personal identifiable information (PII) varies across different jurisdictions (GDPR, HIPAA, PCI etc.), so please check what applies in your case.

Key server location

Provide the URL to an HKP or LDAP key server. Use this setting to administrate PGP keys centrally instead of requiring each user to provide his or her own PGP key.

For HKP servers, use either http or hkp or https or hkps URL schemes to provide the PGP key server URL. 

For LDAP servers, use either ldap or ldaps URL schemes to provide the PGP key server URL. LDAP servers are required to follow the structure as in Broadcom's PGP Universal Server, also supported by GnuPG.

For more information about public PGP key servers, see PGP Key Retrieval.

Note that this is not a required setting. If left empty (or erased), a key server will just not be used, and only user profiles PGP keys will be used.

Prior to version 3.4, only HKP based key servers were supported.

Outbound Proxy

If your Jira is operated behind an outbound proxy that limits access to external domains, please make sure that the key server URL is added to the exception list, so the key server can be accessed.

For details on operating Jira with an outbound proxy, please refer to the Atlassian documentation. 

Incoming email

If checked, user keys attached to incoming emails are extracted and stored as the user's public key for encryption of all emails to this user. For the automatic extraction to take place, it is required that the email is signed properly. This option may be used as a simple way for users to provide their public key. Note that such keys will override keys in key servers.

If you have configured Jira to create new users from incoming emails (or new customers in Jira Service Management), then the user may not yet exist during incoming email processing. In this case, the extracted key will be saved in an intermediate storage, and then added to the user after it has been created by Jira.

Prior to version 3.2, key extraction from incoming email was not available.

Prior to version 3.5, deferred key storage for new users was not available.

User override

Allow user keys

If checked, users are allowed to provide their own PGP keys in the user profile. If a suitable PGP key is provided in both, the global key server and the user profile, the one from the user profile will be used.

Allow customer uploads

Only if you run Jira Service Management, another checkbox will display to separately allow or disallow service desk customers to upload their own PGP key from their profile page.

Prior to version 3.3, it was not possible for Jira Service Management customers to upload their own PGP keys.

Expire Cache

When this button is hit, all S/MIME certificates and PGP keys from a server or key store are marked expired. Consequently, next time when an S/MIME certificate or PGP key is needed for encryption, they will be retrieved freshly from the key store or key server. Use this when you want S/Notify to reload certificates and keys.

If you change the key store location or key server url, this also expires the cache, so after that, all certificates and keys will be retrieved from the new key store or key server.

Note that the key store or key server is not queried, if the user has provided an S/MIME certificate or PGP key in his or her user profile.

Related articles