User Key Management - S/Notify for Jira

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

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 S/MIME. 

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

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 (i.e. one that is not used in the user directories). 

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 necessary if the server requires authentication to read user attributes.

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).

Search 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 an email address.

User Email Attribute

Attribute name under which the email address is stored. Usually "mail". 

Follow Referrals

When enabled, search will be extended to another server if the LDAP server returns a referral. This should only be used when necessary, because it may significantly slow down LDAP search.

This is not uncommon with Active Directory servers. With referral chasing enabled in Active Directory, the client could go from domain to domain in the Active Directory tree trying to satisfy the request if the query cannot be satisfied by the initial domain. This method can be extremely time-consuming. If multiple servers need to be searched, then using the Active Directory's Global Catalog might be the better solution. To connect to the Global Catalog, in the LDAP connection setup, replace 389 by port 3268, or port 686 by 3269, respectively.

Incoming email

Extract certificates

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.

User

Allow user uploads

If checked, Jira users are allowed to upload their own S/MIME certificates from their user profile page. If a certificate is uploaded by the user, it will take precedence over any other sources.

Allow customer uploads

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.

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 one of the following formats:

• GPGP Keyring PGP Binary
  PGP binary file format. Usual file name suffixes are: gpg, pgp, pkr
• GPG Keyring ASCII-Armored
  This format is a common format used to export and transmit public keys. It is, as the name implies, encoded in ASCII. Usual file name suffixes are: asc, txt
• GPGP KeyBox
  This format has been introduced with GPG 2.1 as a replacement for the GPG Keyring format. Usual file name suffix: kbx 

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.

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.

User

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.

Verify Settings

Before or after updating the settings, it is possible to run a verification.

The verification uses the given email address (by default it's your own) and searches all configured sources for matching S/MIME certificates and PGP keys. The result of the search will be listed, including any error that may have been encountered. This allows to easily check for both, configuration problems as well as issues of a specific user.

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 update any of the configuration options, this also expires the cache, so after that, all certificates and keys will be retrieved again.

Note that other sources are not queried if the user has provided an S/MIME certificate or PGP key in his or her user profile.

Related articles