User Key Management - S/Notify for Bitbucket

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

Under this configuration entry, the public PGP keys or S/MIME certificates for Bitbucket users are managed. They are used for the encryption of outgoing emails.

For this, you will find the following configuration options:

Global User Key Management

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 Certificate Keystore. 

Key store location

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

User directory

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

This setting requires that an LDAP server is used as a Bitbucket 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:

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.

User

Allow user uploads

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

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 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 Bitbucket 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 Bitbucket with an outbound proxy, please refer to the Atlassian documentation. 

User

Allow user uploads

When checked, users are allowed to upload 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.

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 the key store or key server 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