Difference between revisions of "Using Your Own SSL Certificate"

[unchecked revision][checked revision]
 
(44 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
== Background ==
 
== Background ==
 +
To ensure authenticity and security, MailStore Server uses TLS certificates in all services it provides. During the installation MailStore Server allows to either
  
−
During the installation of MailStore Server, an SSL certificate is generated which MailStore Web Access/Outlook Add-In can use for access via HTTPS. Since the certificate is issued to the server name ''MailStoreServer'' and does not come from a reliable certification authority (CA), it is not trusted by the client side.  
+
* create a self-signed certificate,
 +
* use an existing certificate,
 +
* or obtain a certificate from Let's Encrypt.
  
−
: [[Datei:MScert.png|300px|center]]
+
The default choice of creating a self-signed certificates is often used when installing MailStore Server for the first time, since it does not have any external dependencies. While this is perfectly fine in a non-production setup, it is not recommended for production use, as self-signed certificates are not trusted by other client computer, due to no being signed by a trusted certificate authority, and user might get used to ignoring certificate warnings.
 +
 
 +
[[File:MScert.png|360px|center]]
 +
 
 +
Because of this, the following or a similar warning message is displayed when opening MailStore Web Access when a self-signed certificate is used.
 +
 
 +
[[File:MSnotrust.png|360px|center]]
 +
 
 +
To eliminate warnings, increase security as well as enhance usability, MailStore needs to be reconfigured to use a certificate that is singed by a trusted certificate authority.
 +
 
 +
The following describes how to manually request and install certificates from a trusted CA. An alternative to this might be obtaining certificates in a more automated fashion from Let's Encrypt. Please refer to [[Using Lets Encrypt Certificates|Using Let's Encrypt Certificates]] for more details.
 +
 
 +
If the ''Personal'' certificate store of the ''Computer account'' does already contain the desired certificate, follow the instructions in the [[#Using_the_Certificate_with_MailStore|Using the Certificate with MailStore]] section.
 +
 
 +
== Prerequisites ==
 +
 
 +
* A trusted [[wikipedia:Certificate_authority|Certificate Authority (CA)]]
 +
* ''certreq'' tool (available on most Windows installations by default)
 +
 
 +
== Creating a New Certificate ==
 +
Unless a certificate for the host name that is to be used for accessing  MailStore Server already exists, follow the below instructions to create a new certificate and import it into Windows' certificate store.
 +
 
 +
=== Creating a Certificate Signing Request (CSR) ===
 +
The following describes how to generate a certificate signing request by using the ''certreq'' tool.
 +
 
 +
* Log on to the MailStore Server computer.
 +
* Prepare a text file <tt>request.inf</tt> with the following content, adjust the ''Subject'' and ''FriendlyName'' values according to your needs. Adjust the ''Subject Alternative Names (SAN)'' in the ''[Extensions]'' section as well. Please note that the ''Common Name (CN)'' in the ''Subject'' is irrelevant for the verification by clients and that all host names must be included as SANs. Additional host names may be added with appending additional ''_continue_'' lines.
 +
 
 +
<pre>
 +
;----------------- request.inf -----------------
 +
[Version]
 +
Signature="$Windows NT$"
 +
 
 +
[NewRequest]
 +
; replace Subject attributes in the line below with real values
 +
Subject = "CN=mailstoreserver.example.com, OU=Department, O=Organisation, L=Locality, S=State, C=CountryCode"
 +
KeySpec = 1
 +
KeyLength = 2048
 +
Exportable = TRUE
 +
FriendlyName = mailstoreserver.example.com
 +
MachineKeySet = TRUE
 +
SMIME = False
 +
PrivateKeyArchive = FALSE
 +
UserProtected = FALSE
 +
UseExistingKeySet = FALSE
 +
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
 +
ProviderType = 12
 +
RequestType = PKCS10
 +
KeyUsage = 0xa0
 
   
 
   
−
Because of this, the following warning message is displayed when calling up MailStore Web Access via HTTPS (SSL):
+
[EnhancedKeyUsageExtension]
 +
OID = 1.3.6.1.5.5.7.3.1 ; this is for Server Authentication
 +
 
 +
[Extensions]
 +
2.5.29.17 = "{text}"
 +
_continue_ = "DNS=*.example.com&"
 +
_continue_ = "DNS=mailstoreserver.example.com&"
 +
</pre>
 +
* Save the file.
 +
* Open an elevated command prompt and navigate to the directory where the ''request.inf'' is stored.
 +
* Create the CSR by executing the following command:
 +
certreq -new request.inf request.csr
 +
 
 +
=== Validating the Certificate Signing Request ===
 +
To verify that the CSR is correct, execute the following command to display it in a human readable format:
 +
 
 +
certutil -dump request.csr
 +
 
 +
=== Submitting the Certificate Signing Request ===
 +
Submit the CSR to your preferred CA. Typically you upload the CSR file to a website of the CA. The CA might ask for the server platform during the submission process. Selecting ''IIS 7'' or ''None of the listed'' should be sufficient. After successful approval of the CSR, you will get the signed certificate in return.
 +
 
 +
<p class="msnote">'''Please note:''' Nowadays the certificate mostly is signed by intermediate CAs. It is required that the certificate of the intermediate CA is imported into the certificate store. Detailed information about the installation process of intermediate CA certificates is typically included in the electronic delivery of your certificate.</p>
 +
 
 +
=== Importing the Certificate ===
 +
* Open an elevated command prompt and navigate to the directory where the certificate file is stored.
 +
* Execute the following command to import the certificate into the computer's personal certificate store:
 +
 
 +
certreq -accept certificate.cer
 +
 
 +
=== Verifying the Import ===
 +
* Log on to the MailStore Server computer as administrator.
 +
* Open the ''Microsoft Management Console (MMC)''
 +
* Add the Certificate Snap-In by following these steps:
 +
** Click on ''File'' > ''Add/Remove Snap-In'' > ''Certificate'' > ''Add >''
 +
** Select ''Computer Account'' and click on ''Next >''
 +
** Select ''Local Computer'' and click on ''Finish''
 +
** Close any open dialog windows
 +
* Click on ''Certificates (Local Computer)'' > ''Personal'' > ''Certificates''
 +
* Double-click on the previously imported certificate
 +
* Make sure that the private key for the certificate is available:
 +
 
 +
[[File:Private_key.png|center]]
  
−
: [[Datei:MSnotrust.png|300px|center]]
+
==== Repairing the Certificate Store ====
−
   
+
Sometimes the matching private key cannot be found although the certificate was imported successfully into the correct certificate store. Try to repair the certificate store as follows:
−
One option for resolving this issue is to make the server on which MailStore Server is installed available under the host name ''MailStoreServer'' (e.g. by adding and A- or CNAME record in the DNS) and installing the certificate in the container of trustworthy root certification authorities on the clients. Because these installations involve a relatively high administrative overhead, MailStore Server provides the option to use signed certificates of your own company CA or certificates of a public certification provider (e.g. VeriSign, eTrust etc.).
+
 
 +
* Open an elevated PowerShell and execute the following command:
 +
 
 +
Get-ChildItem Cert:\LocalMachine\My | select Subject, Serialnumber, Thumbprint, HasPrivateKey
 +
 
 +
* Check the subjects, serialnumbers and fingerprints of the installed certificates, to identify the certificate to be used by MailStore.
 +
* Repair the corresponding certificate store by executing the following command, where ''SerialNumber'' is the serial number of the certificate that should be used.
 +
 
 +
  certutil -repairstore my SerialNumber
 +
 
 +
=== Using the Certificate with MailStore ===
 +
* Open the MailStore Server Service Configuration.
 +
* Select ''Network Settings''.
 +
* In the section you want to change to certificate for, click on the button next to the ''Server Certificate'' field and select ''Select from Certificate Store...''
 +
* Choose the new certificate from the certificate store.
 +
* Confirm your selection and restart the MailStore Server service.
 +
 
 +
== Importing an Existing Certificate ==
 +
Typically certificates are exchanged between computers by means of Personal Information Exchange (PFX/P12) containers. These can, for example, be created using the export functions of the MMC Snap-In ''Certificates''.
 +
 
 +
=== Optional: Creating a PFX Container with OpenSSL/LibreSSL ===
 +
When the original CSR was not created with Windows' own tools or not even created on a Windows computer, it is unlikely that the private key or the vertificate is available in Windows' certificate store of the MailStore Server computer, but on stored on the file system instead.
  
−
Um MailStore Server für die Verwendung eines eigenes Zertifikats zu konfigurieren, gehen Sie wie im Folgenden beschrieben vor.
+
In this case, a Personal Information Exchange (PFX) container needs to be created first. This container holds the certificate, private key, and all certificates of the certificate chain. After that, the PFX container can by imported into Windows' certificate store.
  
−
== Installing the Certificate ==
+
The following steps need to be executed to convert the certificate files into a PFX container with OpenSSL or LibreSSL:
  
−
* Melden Sie sich am Server als Administrator an.
+
* Copy the certificate, private key and the certificates of the certificate chain into the OpenSSL or LibreSSL directory.
−
* Klicken Sie ''Start | Ausführen''.
+
* Open an elevated command prompt and navigate to this directory.
−
* Führen Sie den Befehl ''mmc'' aus.
+
* Create the PFX container by executing the following command, adjust the file names of necessary:
−
* Wählen Sie nun ''Datei | Snap-In hinzufügen/entfernen | Hinzufügen | Zertifikate''.
+
  openssl pkcs12 -export -out certificate.pfx -inkey private_key.key -in certificate.crt -certfile chain_bundle_file.crt
−
* Wählen Sie in der nun folgenden Auswahl ''lokales Computerkonto'' und anschließend ''lokaler Computer''.
+
* In some case the created PFX container is not compatible with the Windows system and the import fails with a password error, even when the password is correct. In that case, append the ''-legacy'' parameter to the command:
−
* Schließen Sie die Auswahl über ''Fertigstellen'' ab und schließen Sie die noch offenen Dialoge.
+
openssl pkcs12 -export -out certificate.pfx -inkey private_key.key -in certificate.crt -certfile chain_bundle_file.crt -legacy
−
* Wählen Sie in der Management Konsole ''Eigene Zertifikate | Zertifikate''.
 
−
* Klicken Sie auf mit der rechten Maustaste auf den Ordner ''Zertifikate'' und wählen Sie ''Alle Aufgaben | Importieren''.
 
−
* Folgen Sie den Anweisungen des Assistenten und wählen Sie die Datei aus, welche das Zertifikat und ggf. den privaten Schlüssel enthält.
 
−
* Wählen Sie auf der Seite ''Zertifikatsspeicher'' den Container ''Eigene Zertifikate'' aus und schließen Sie den Assistenten anschließend ab.
 
−
* Das Zertifikat wird nun im Container ''Eigene Zertifikate'' angezeigt.
 
−
* Zur Kontrolle öffnen Sie das Zertifikat über einen Doppelklick und vergewissern Sie sich, dass Sie über den privaten Schlüssel für das Zertifikat verfügen.
 
  
−
: [[Datei:Private_key.png|300px|center]]
+
=== Importing a PFX container ===
 +
* Open the MailStore Server Service Configuration.
 +
* Select ''Network Settings''.
 +
* In the section you want to change to certificate for, click on the button next to the ''Server Certificate'' field and select ''Import from file...''
 +
* Choose the PFX file.
 +
* If the PFX file has been password protected, you are being ask to provide the password now.
 +
* Confirm your selection and restart the MailStore Server service.
  
−
== Using the Certificate with MailStore Server ==
+
== Weblinks ==
 +
* [https://technet.microsoft.com/en-us/library/dn296456.aspx Microsoft Technet: Certreq]
 +
* [https://technet.microsoft.com/en-us/library/cc732443.aspx Microsoft Technet: Certutil]
 +
* [https://technet.microsoft.com/de-de/library/ff625722.aspx Microsoft Technet: How to Request a Certificate With a Custom Subject Alternative Name]
 +
* [https://www.libressl.org/ LibreSSL]
 +
* [https://www.openssl.org/docs/apps/openssl.html OpenSSL Documentation]
  
−
* Open the  MailStore Server base configuration.
+
[[de:Verwendung_eigener_SSL_Zertifikate]]
−
* Select  ''Web Access/Outlook Addin'' and click on ''Configure HTTP/HTTPS Access''.
+
[[en:Using Your Own SSL Certificate]]
−
* Click on ''Select Certificate'' and choose the new certificate.
 
−
* Confirm your entries and restart the MailStore Server service.
 

Latest revision as of 13:35, 6 November 2024

Background

To ensure authenticity and security, MailStore Server uses TLS certificates in all services it provides. During the installation MailStore Server allows to either

  • create a self-signed certificate,
  • use an existing certificate,
  • or obtain a certificate from Let's Encrypt.

The default choice of creating a self-signed certificates is often used when installing MailStore Server for the first time, since it does not have any external dependencies. While this is perfectly fine in a non-production setup, it is not recommended for production use, as self-signed certificates are not trusted by other client computer, due to no being signed by a trusted certificate authority, and user might get used to ignoring certificate warnings.

MScert.png

Because of this, the following or a similar warning message is displayed when opening MailStore Web Access when a self-signed certificate is used.

MSnotrust.png

To eliminate warnings, increase security as well as enhance usability, MailStore needs to be reconfigured to use a certificate that is singed by a trusted certificate authority.

The following describes how to manually request and install certificates from a trusted CA. An alternative to this might be obtaining certificates in a more automated fashion from Let's Encrypt. Please refer to Using Let's Encrypt Certificates for more details.

If the Personal certificate store of the Computer account does already contain the desired certificate, follow the instructions in the Using the Certificate with MailStore section.

Prerequisites

Creating a New Certificate

Unless a certificate for the host name that is to be used for accessing MailStore Server already exists, follow the below instructions to create a new certificate and import it into Windows' certificate store.

Creating a Certificate Signing Request (CSR)

The following describes how to generate a certificate signing request by using the certreq tool.

  • Log on to the MailStore Server computer.
  • Prepare a text file request.inf with the following content, adjust the Subject and FriendlyName values according to your needs. Adjust the Subject Alternative Names (SAN) in the [Extensions] section as well. Please note that the Common Name (CN) in the Subject is irrelevant for the verification by clients and that all host names must be included as SANs. Additional host names may be added with appending additional _continue_ lines.
;----------------- request.inf -----------------
[Version]
Signature="$Windows NT$"

[NewRequest]
; replace Subject attributes in the line below with real values
Subject = "CN=mailstoreserver.example.com, OU=Department, O=Organisation, L=Locality, S=State, C=CountryCode"
KeySpec = 1
KeyLength = 2048
Exportable = TRUE
FriendlyName = mailstoreserver.example.com
MachineKeySet = TRUE
SMIME = False
PrivateKeyArchive = FALSE
UserProtected = FALSE
UseExistingKeySet = FALSE
ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
ProviderType = 12
RequestType = PKCS10
KeyUsage = 0xa0
 
[EnhancedKeyUsageExtension]
OID = 1.3.6.1.5.5.7.3.1 ; this is for Server Authentication

[Extensions]
2.5.29.17 = "{text}"
_continue_ = "DNS=*.example.com&"
_continue_ = "DNS=mailstoreserver.example.com&"
  • Save the file.
  • Open an elevated command prompt and navigate to the directory where the request.inf is stored.
  • Create the CSR by executing the following command:
certreq -new request.inf request.csr

Validating the Certificate Signing Request

To verify that the CSR is correct, execute the following command to display it in a human readable format: 

certutil -dump request.csr

Submitting the Certificate Signing Request

Submit the CSR to your preferred CA. Typically you upload the CSR file to a website of the CA. The CA might ask for the server platform during the submission process. Selecting IIS 7 or None of the listed should be sufficient. After successful approval of the CSR, you will get the signed certificate in return.

Please note: Nowadays the certificate mostly is signed by intermediate CAs. It is required that the certificate of the intermediate CA is imported into the certificate store. Detailed information about the installation process of intermediate CA certificates is typically included in the electronic delivery of your certificate.

Importing the Certificate

  • Open an elevated command prompt and navigate to the directory where the certificate file is stored.
  • Execute the following command to import the certificate into the computer's personal certificate store:
certreq -accept certificate.cer

Verifying the Import

  • Log on to the MailStore Server computer as administrator.
  • Open the Microsoft Management Console (MMC)
  • Add the Certificate Snap-In by following these steps:
    • Click on File > Add/Remove Snap-In > Certificate > Add >
    • Select Computer Account and click on Next >
    • Select Local Computer and click on Finish
    • Close any open dialog windows
  • Click on Certificates (Local Computer) > Personal > Certificates
  • Double-click on the previously imported certificate
  • Make sure that the private key for the certificate is available:
Private key.png

Repairing the Certificate Store

Sometimes the matching private key cannot be found although the certificate was imported successfully into the correct certificate store. Try to repair the certificate store as follows:

  • Open an elevated PowerShell and execute the following command:
Get-ChildItem Cert:\LocalMachine\My | select Subject, Serialnumber, Thumbprint, HasPrivateKey
  • Check the subjects, serialnumbers and fingerprints of the installed certificates, to identify the certificate to be used by MailStore.
  • Repair the corresponding certificate store by executing the following command, where SerialNumber is the serial number of the certificate that should be used.
certutil -repairstore my SerialNumber

Using the Certificate with MailStore

  • Open the MailStore Server Service Configuration.
  • Select Network Settings.
  • In the section you want to change to certificate for, click on the button next to the Server Certificate field and select Select from Certificate Store...
  • Choose the new certificate from the certificate store.
  • Confirm your selection and restart the MailStore Server service.

Importing an Existing Certificate

Typically certificates are exchanged between computers by means of Personal Information Exchange (PFX/P12) containers. These can, for example, be created using the export functions of the MMC Snap-In Certificates.

Optional: Creating a PFX Container with OpenSSL/LibreSSL

When the original CSR was not created with Windows' own tools or not even created on a Windows computer, it is unlikely that the private key or the vertificate is available in Windows' certificate store of the MailStore Server computer, but on stored on the file system instead.

In this case, a Personal Information Exchange (PFX) container needs to be created first. This container holds the certificate, private key, and all certificates of the certificate chain. After that, the PFX container can by imported into Windows' certificate store.

The following steps need to be executed to convert the certificate files into a PFX container with OpenSSL or LibreSSL:

  • Copy the certificate, private key and the certificates of the certificate chain into the OpenSSL or LibreSSL directory.
  • Open an elevated command prompt and navigate to this directory.
  • Create the PFX container by executing the following command, adjust the file names of necessary:
 openssl pkcs12 -export -out certificate.pfx -inkey private_key.key -in certificate.crt -certfile chain_bundle_file.crt
  • In some case the created PFX container is not compatible with the Windows system and the import fails with a password error, even when the password is correct. In that case, append the -legacy parameter to the command:
openssl pkcs12 -export -out certificate.pfx -inkey private_key.key -in certificate.crt -certfile chain_bundle_file.crt -legacy

Importing a PFX container

  • Open the MailStore Server Service Configuration.
  • Select Network Settings.
  • In the section you want to change to certificate for, click on the button next to the Server Certificate field and select Import from file...
  • Choose the PFX file.
  • If the PFX file has been password protected, you are being ask to provide the password now.
  • Confirm your selection and restart the MailStore Server service.

Weblinks

Retrieved from "https://help.mailstore.com/en/server/index.php?title=Using_Your_Own_SSL_Certificate&oldid=7708"