(1.x) User Key Management - S/Notify for Bitbucket

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:

User override

When Allow user certificates is checked, users are allowed to upload their own S/MIME certificates in the user profile. 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.

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 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 override

When Allow user keys is 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.

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