How to Setup S/MIME Integration

For development purposes, it's possible to set up S/MIME integration for a local Zammad instance. However, since the approach uses self-generated test certificates, this is considered unsafe for production. You've been warned!

Configure S/MIME Integration

Navigate to the System > Integrations > S/MIME section in GUI, and turn on the toggle switch on top to activate the feature.

Upload Sender Certificate & Private Key

In the same screen, click on the Add Certificate button.

Paste the following text in the Paste Certificate box:

-----BEGIN TRUSTED CERTIFICATE-----
MIIEmTCCA4GgAwIBAgIJAOOVkfcMlOvoMA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNV
BAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxpbjEaMBgGA1UE
CgwRWmFtbWFkIEZvdW5kYXRpb24xFDASBgNVBAsMC0RldmVsb3BtZW50MRMwEQYD
VQQDDAp6YW1tYWQub3JnMB4XDTIzMDExMTEwNDUwMloXDTMzMDEwODEwNDUwMlow
gZwxCzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxp
bjEaMBgGA1UECgwRWmFtbWFkIEZvdW5kYXRpb24xFDASBgNVBAsMC0RldmVsb3Bt
ZW50MRgwFgYDVQQDDA9aYW1tYWQgSGVscGRlc2sxHzAdBgkqhkiG9w0BCQEWEHph
bW1hZEBsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCd
7ExEQqbNisuu/OB48dMZ+dYWOFgYC3z/JAiDexPYNzcZz6JWajaGwJTR2cYJxiyV
rNhKusb7YaqOi20D1X4PKn8Siq2HWIMzg5MCR/IQs7tu6f86+pZS6Hyce89ttHEh
j3gcv6Ms0ii6XpIAYUK2O7ZMaCiCpiUmmCwwcmv79GYOaFwfDt5WIhFuyKroxAXA
qObgNai4xu4K8pj3SXed0W+YVJ1I+jCbY2V25iKLs0w9DaPUrhlbGeKezEwRURGD
lGlIGX86BXB8tLFEG2qLhKYrokUDltIU+99Z/GiFhZRuuyL8BUv8kBbPI+YyhiP+
e990WC0uipu0sorrAfbTAgMBAAGjggEBMIH+MAkGA1UdEwQCMAAwCwYDVR0PBAQD
AgXgMB0GA1UdDgQWBBQulBRC4PUBK0VlRb1XgRSx3PNMbTAbBgNVHREEFDASgRB6
YW1tYWRAbG9jYWxob3N0MBMGA1UdJQQMMAoGCCsGAQUFBwMEMIGSBgNVHSMEgYow
gYeheqR4MHYxCzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcM
BkJlcmxpbjEaMBgGA1UECgwRWmFtbWFkIEZvdW5kYXRpb24xFDASBgNVBAsMC0Rl
dmVsb3BtZW50MRMwEQYDVQQDDAp6YW1tYWQub3JnggkAoyQmhzPcTqcwDQYJKoZI
hvcNAQELBQADggEBAFSPJoakV7qsq8+0SSSp82O59kAmD2xMojzdv9wu+99Y5d4r
Z/oN0S2ZYBu4d0v+RNysIaCSbxt8DKbZ67slhSLl7vON9pkbq9RbvYlVIcB0As+y
a3MODFKLPOE6UfszW8TGsyWJrUXufucb4MxBICTa2ZQF+vmg9XSngO6emgo9UQWM
Ojl/J0ETQK/oDVO0QtcCv12dnefK6maHuAHA6+MQ+PsxTFRa7VPPsMKM0sRMmyP8
Nm154jJaJIb/QLdhPZ73aBmSopOIUOfc7Q39cd7TXaFHBMwe0wXVeuS4N7M+2a+s
+Wmv1N+1HnB5/NT7GF3lmrB+PF/oPuMkOIcmbXMwIjAKBggrBgEFBQcDBKAUBggr
BgEFBQcDAgYIKwYBBQUHAwE=
-----END TRUSTED CERTIFICATE-----

Click on the Add button.
Click on the Add Private Key button.

Paste the following text in the Paste Private Key box:

Leave Enter Private Key Secret box empty.
Click on the Add button.

The test sender certificate above was generated for the following sender email address: zammad@localhost. In case your sender address is different, please see below how to re-generate it.

Upload Recipient Certificate

In the same screen, click again on the Add Certificate button.

Paste the following text in the Paste Certificate box:

-----BEGIN TRUSTED CERTIFICATE-----
MIIEpTCCA42gAwIBAgIJAOOVkfcMlOvnMA0GCSqGSIb3DQEBCwUAMHYxCzAJBgNV
BAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxpbjEaMBgGA1UE
CgwRWmFtbWFkIEZvdW5kYXRpb24xFDASBgNVBAsMC0RldmVsb3BtZW50MRMwEQYD
VQQDDAp6YW1tYWQub3JnMB4XDTIzMDExMTA4NTExNloXDTMzMDEwODA4NTExNlow
gaAxCzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJsaW4xDzANBgNVBAcMBkJlcmxp
bjEaMBgGA1UECgwRWmFtbWFkIEZvdW5kYXRpb24xFDASBgNVBAsMC0RldmVsb3Bt
ZW50MRUwEwYDVQQDDAxOaWNvbGUgQnJhdW4xJjAkBgkqhkiG9w0BCQEWF25pY29s
ZS5icmF1bkB6YW1tYWQub3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
AQEAq1/HC+dh0UoRvuMB/7pkydTLcivyxt5OVgmGsKT32YNrmJctYs38It2jiTzJ
SIWMeAqTaAaRjjy3P3dUv9FAZFTEPI+zc2tuWCaXnO7ccvpz8QBTZsZZC0gKmXqo
4/+qrfUJqC72DeuZlTg2iwaSp63Yeet5ShuVbF+gTgO+vMlRnaKMXNuIJM14Auzb
Fsdc+0vMPE52arWORK9woajOCUn1xfGTu917+D24gX6Xic9gnLJKXNYyL7wctVS+
US3FPdJLqeNNb2rJyZcrLBtzWXIiVJYnHx4knrWP1m+c3ThQEPeQef/DDws3+3Ub
8WYay7oqO7eujYSFBTX1xlPeQwIDAQABo4IBCTCCAQUwCQYDVR0TBAIwADALBgNV
HQ8EBAMCBeAwHQYDVR0OBBYEFFC5iaStg5uoFcetE2u+7rgffdKtMCIGA1UdEQQb
MBmBF25pY29sZS5icmF1bkB6YW1tYWQub3JnMBMGA1UdJQQMMAoGCCsGAQUFBwME
MIGSBgNVHSMEgYowgYeheqR4MHYxCzAJBgNVBAYTAkRFMQ8wDQYDVQQIDAZCZXJs
aW4xDzANBgNVBAcMBkJlcmxpbjEaMBgGA1UECgwRWmFtbWFkIEZvdW5kYXRpb24x
FDASBgNVBAsMC0RldmVsb3BtZW50MRMwEQYDVQQDDAp6YW1tYWQub3JnggkAoyQm
hzPcTqcwDQYJKoZIhvcNAQELBQADggEBAEgk7pW68d88cgD38oyHaMqQdQ0Odtzh
78a6u2Bki2BtYK+4AwCWdeb+lZLKj6W/CPOWPJriFRMqiRQ6N6eIPRc4x70Q0fMJ
JXAWQA4eliHFGLzA+YMyBKiW1EfLU6pIkvWONLG3oVch4gAccHgY6h436OmHtoRr
VPiz25xCSe5YZWpLY1KeZ7Ucv51qaMlRHNdwB4ixETFG54bbK6mATiSCw2Wtwqlj
qKX2l5VYSxhC51lveLQaVlQHy3nj1M2uGQN6Jv1wc0Pe6Twu3itqYZrJnTJdoq4K
ty1IuHWXx7wJ64xa+Rbx5MHXsz1jsML8+UL9DgSw0zjL+BJcF+wuaEEwIjAKBggr
BgEFBQcDBKAUBggrBgEFBQcDAgYIKwYBBQUHAwE=
-----END TRUSTED CERTIFICATE-----

Click on the Add button.

The test recipient certificate above was generated for the following customer email address: nicole.braun@zammad.org. In case your recipient address is different, please see below how to re-generate it.

Upload CA Certificate

In the same screen, click on the Add Certificate button.

Paste the following text in the Paste Certificate box:

Click on the Add button.

The test CA certificate above was used to sign both the test sender and test recipient certificates.

Create a Test Email Ticket with Encrypted & Signed Content

Go to new ticket screen.
Switch to the Send Email article type.
Provide a Title.
Choose a Customer called Nicole Braun.
Provide some Text.
Choose a Group.
Verify that both Encrypt and Sign toggle buttons are now active.
Click on the Create button.
Verify that the first article has a Security field with both Encrypted and Signed flags.

Re-generate Test Certificates

You will need an installation of a recent openssl utility for the following commands.

Generate CA Certificate & Private Key

Navigate to an empty directory.

Create a text configuration file called ca.conf with the following content:

[req]
distinguished_name = req_distinguished_name

[req_distinguished_name]
countryName = Country Name (2 letter code)
countryName_default = DE
countryName_min = 2
countryName_max = 2
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Berlin
stateOrProvinceName_max = 32
localityName = Locality Name (eg, city)
localityName_default = Berlin
0.organizationName = Organization Name (eg, company)
0.organizationName_default = Zammad Foundation
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName_default = Development
commonName = Common Name (e.g. server FQDN or YOUR name)
commonName_default = zammad.org
commonName_max = 64
emailAddress = Email Address
emailAddress_default =
emailAddress_max = 40

Adjust all *_default values to match desired settings, except emailAddress_default. Please leave it empty.

Run the following command in the same directory:

openssl req -x509 -new -nodes -days 3650 -config ca.conf -keyout ca.key -out ca.crt

Confirm each field with a return (the value will be pre-populated from the configuration file).

You can now upload your new test CA certificate. Either upload the actual text file (ca.crt) or paste its content in appropriate box. Note that in this case you should NOT upload the generated private key since the certificate may be used only for the trust chain verification.

Generate Sender Certificate & Private Key

Navigate to an empty directory.

Create a text configuration file called sender.conf with the following content:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req

[req_distinguished_name]
countryName = Country Name (2 letter code)
countryName_default = DE
countryName_min = 2
countryName_max = 2
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Berlin
stateOrProvinceName_max = 32
localityName = Locality Name (eg, city)
localityName_default = Berlin
0.organizationName = Organization Name (eg, company)
0.organizationName_default = Zammad GmbH
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName_default = Development
commonName = Common Name (e.g. server FQDN or YOUR name)
commonName_default = Zammad Foundation
commonName_max = 64
emailAddress = Email Address
emailAddress_default = zammad@localhost
emailAddress_max = 40

[v3_req]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
subjectAltName = email:copy
extendedKeyUsage = emailProtection

Adjust all *_default values to match desired settings. The most important is emailAddress_default which must match your sender's email address.

Run the following command in the same directory to generate the certificate request:
```
openssl req -new -nodes -keyout sender.key -out sender.csr -config sender.conf
```

Confirm each field with a return (the value will be pre-populated from the configuration file).

Create a text configuration file called v3_ca.conf with the following content:

[v3_ca]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
subjectAltName = email:copy
extendedKeyUsage = emailProtection
authorityKeyIdentifier = keyid,issuer

Run the following command in the same directory to generate and sign the certificate:

openssl x509 -req -days 3650 -in sender.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out sender.crt -addtrust emailProtection -addreject clientAuth -addreject serverAuth -trustout -extensions v3_ca -extfile v3_ca.conf

You can now upload your new test sender certificate & private key. Either upload the actual text files (sender.crt and sender.key) or paste their contents in appropriate boxes. Remember to omit the input for the private key secret since it was not defined during the re-generation, but don't skip the private key upload since the certificate may be used for signing and decryption.

Generate Recipient Certificate & Private Key

Navigate to an empty directory.

Create a text configuration file called recipient.conf with the following content:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req

[req_distinguished_name]
countryName = Country Name (2 letter code)
countryName_default = DE
countryName_min = 2
countryName_max = 2
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Berlin
localityName = Locality Name (eg, city)
localityName_default = Berlin
0.organizationName = Organization Name (eg, company)
0.organizationName_default = Zammad Foundation
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName_default = Development
commonName = Common Name (e.g. server FQDN or YOUR name)
commonName_default = Nicole Braun
commonName_max = 64
emailAddress = Email Address
emailAddress_default = nicole.braun@zammad.org
emailAddress_max = 40

[v3_req]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
subjectAltName = email:copy
extendedKeyUsage = emailProtection

Adjust all *_default values to match desired settings. The most important is emailAddress_default which must match your recipient's email address.

Run the following command in the same directory to generate the certificate request:

openssl req -new -nodes -keyout recipient.key -out recipient.csr -config recipient.conf

Confirm each field with a return (the value will be pre-populated from the configuration file).

Create a text configuration file called v3_ca.conf with the following content:

[v3_ca]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier = hash
subjectAltName = email:copy
extendedKeyUsage = emailProtection
authorityKeyIdentifier = keyid,issuer

Run the following command in the same directory to generate and sign the certificate:

openssl x509 -req -days 3650 -in recipient.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out recipient.crt -addtrust emailProtection -addreject clientAuth -addreject serverAuth -trustout -extensions v3_ca -extfile v3_ca.conf

You can now upload your new test recipient certificate. Either upload the actual text file (recipient.crt) or paste its content in appropriate box. Note that in this case you should NOT upload the generated private key since the certificate may be used only for encryption.

Other Useful OpenSSL commands

Dump the Text Content of a Certificate

openssl x509 -in sender.crt -text

Export Certificate to PKCS12 for Usage in Email Clients

openssl pkcs12 -export -in sender.crt -inkey sender.key -out sender.p12

how-to-setup-smime-integration.md 16 KB Постоянная ссылка История Исходник

How to Setup S/MIME Integration

Configure S/MIME Integration

Upload Sender Certificate & Private Key

Upload Recipient Certificate

Upload CA Certificate

Create a Test Email Ticket with Encrypted & Signed Content

Re-generate Test Certificates

Generate CA Certificate & Private Key

Generate Sender Certificate & Private Key

Generate Recipient Certificate & Private Key

Other Useful OpenSSL commands

Dump the Text Content of a Certificate

Export Certificate to PKCS12 for Usage in Email Clients

how-to-setup-smime-integration.md 16 KB

Постоянная ссылка История Исходник