2020-10-24 00:08:35 +00:00
---
2022-05-30 00:08:35 +00:00
stage: Systems
2020-12-01 18:09:42 +00:00
group: Distribution
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-24 00:08:35 +00:00
---
2021-06-02 21:10:00 +00:00
# Signing outgoing email with S/MIME **(FREE SELF)**
2019-07-10 19:40:28 +00:00
2019-10-01 03:05:57 +00:00
Notification emails sent by GitLab can be signed with S/MIME for improved
2019-07-10 19:40:28 +00:00
security.
2020-11-04 03:09:14 +00:00
Be aware that S/MIME certificates and TLS/SSL certificates are not the
2019-07-10 19:40:28 +00:00
same and are used for different purposes: TLS creates a secure channel, whereas
S/MIME signs and/or encrypts the message itself
## Enable S/MIME signing
This setting must be explicitly enabled and a single pair of key and certificate
2019-09-10 06:44:56 +00:00
files must be provided:
2019-07-10 19:40:28 +00:00
2019-09-10 06:44:56 +00:00
- Both files must be PEM-encoded.
- The key file must be unencrypted so that GitLab can read it without user
2019-07-10 19:40:28 +00:00
intervention.
2019-09-10 06:44:56 +00:00
- Only RSA keys are supported.
2019-07-10 19:40:28 +00:00
2020-04-21 15:21:10 +00:00
Optionally, you can also provide a bundle of CA certs (PEM-encoded) to be
2022-06-21 00:08:43 +00:00
included on each signature. This is typically an intermediate CA.
2020-04-21 15:21:10 +00:00
2020-12-04 21:09:29 +00:00
WARNING:
2020-07-16 06:09:33 +00:00
Be mindful of the access levels for your private keys and visibility to
2019-07-10 19:40:28 +00:00
third parties.
2019-09-10 06:44:56 +00:00
**For Omnibus installations:**
1. Edit `/etc/gitlab/gitlab.rb` and adapt the file paths:
```ruby
gitlab_rails['gitlab_email_smime_enabled'] = true
gitlab_rails['gitlab_email_smime_key_file'] = '/etc/gitlab/ssl/gitlab_smime.key'
gitlab_rails['gitlab_email_smime_cert_file'] = '/etc/gitlab/ssl/gitlab_smime.crt'
2020-04-21 15:21:10 +00:00
# Optional
gitlab_rails['gitlab_email_smime_ca_certs_file'] = '/etc/gitlab/ssl/gitlab_smime_cas.crt'
2019-09-10 06:44:56 +00:00
```
1. Save the file and [reconfigure GitLab ](restart_gitlab.md#omnibus-gitlab-reconfigure ) for the changes to take effect.
2020-07-16 06:09:33 +00:00
The key needs to be readable by the GitLab system user (`git` by default).
2019-09-10 06:44:56 +00:00
**For installations from source:**
1. Edit `config/gitlab.yml` :
```yaml
email_smime:
# Uncomment and set to true if you need to enable email S/MIME signing (default: false)
enabled: true
# S/MIME private key file in PEM format, unencrypted
# Default is '.gitlab_smime_key' relative to Rails.root (i.e. root of the GitLab app).
key_file: /etc/pki/smime/private/gitlab.key
# S/MIME public certificate key in PEM format, will be attached to signed messages
# Default is '.gitlab_smime_cert' relative to Rails.root (i.e. root of the GitLab app).
cert_file: /etc/pki/smime/certs/gitlab.crt
2020-04-21 15:21:10 +00:00
# S/MIME extra CA public certificates in PEM format, will be attached to signed messages
# Optional
ca_certs_file: /etc/pki/smime/certs/gitlab_cas.crt
2019-09-10 06:44:56 +00:00
```
1. Save the file and [restart GitLab ](restart_gitlab.md#installations-from-source ) for the changes to take effect.
2020-07-16 06:09:33 +00:00
The key needs to be readable by the GitLab system user (`git` by default).
2019-09-10 06:44:56 +00:00
2021-09-28 03:11:11 +00:00
### How to convert S/MIME PKCS #12 format to PEM encoding
2019-07-10 19:40:28 +00:00
2021-09-28 03:11:11 +00:00
Typically S/MIME certificates are handled in binary Public Key Cryptography Standards (PKCS) #12 format
(`.pfx` or `.p12` extensions), which contain the following in a single encrypted file:
2019-07-10 19:40:28 +00:00
2019-09-10 06:44:56 +00:00
- Public certificate
2019-07-10 19:40:28 +00:00
- Intermediate certificates (if any)
- Private key
2021-09-23 09:09:51 +00:00
To export the required files in PEM encoding from the PKCS #12 file, the
2020-09-30 21:10:09 +00:00
`openssl` command can be used:
2019-07-10 19:40:28 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-10 19:40:28 +00:00
#-- Extract private key in PEM encoding (no password, unencrypted)
$ openssl pkcs12 -in gitlab.p12 -nocerts -nodes -out gitlab.key
#-- Extract certificates in PEM encoding (full certs chain including CA)
$ openssl pkcs12 -in gitlab.p12 -nokeys -out gitlab.crt
```