Merge branch 'docs/smime-signing-omnibus-example' into 'master'

docs: add full omnibus example for smime signing

See merge request gitlab-org/gitlab-ce!32146

1 files changed, 39 insertions, 12 deletions

diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md
index b2e3bf8487b..530553ec1c4 100644
--- a/doc/administration/smime_signing_email.md
+++ b/doc/administration/smime_signing_email.md
@@ -11,29 +11,56 @@ 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
-files must be provided in `gitlab.rb` or `gitlab.yml` if you are using Omnibus
-GitLab or installed GitLab from source respectively:
-
-```yaml
-email_smime:
-  enabled: true
-  key_file: /etc/pki/smime/private/gitlab.key
-  cert_file: /etc/pki/smime/certs/gitlab.crt
-```
+files must be provided:
 
-- Both files must be provided PEM-encoded.
-- The key file must be unencrypted so that Gitlab can read it without user
+- Both files must be PEM-encoded.
+- The key file must be unencrypted so that GitLab can read it without user
   intervention.
+- Only RSA keys are supported.
 
 NOTE: **Note:** Be mindful of the access levels for your private keys and visibility to
 third parties.
 
+**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'
+   ```
+
+1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
+
+NOTE: **Note:** The key needs to be readable by the GitLab system user (`git` by default).
+
+**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
+   ```
+
+1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
+
+NOTE: **Note:** The key needs to be readable by the GitLab system user (`git` by default).
+
 ### How to convert S/MIME PKCS#12 / PFX format to PEM encoding
 
 Typically S/MIME certificates are handled in binary PKCS#12 format (`.pfx` or `.p12`
 extensions), which contain the following in a single encrypted file:
 
-- Server certificate
+- Public certificate
 - Intermediate certificates (if any)
 - Private key