Difference between revisions of "Working with SSL Certificates"

[unchecked revision][checked revision]
 
(46 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
== Generating a CSR and importing the certificate with certreq ==
+
Although various methods exist to create and import SSL certificates, this task can be laborious on Windows servers where no certificate policy exists (i.e. standalone servers). This article describes how to manually create and verify a certificate signing requests (CSR) and import the certificate after the CSR has been signed by a certificate authority, using Microsoft's ''Certreq'' tool.
  
−
* Log on on the host which runs the ''Client Access Server''.
+
Service Providers who already possess certificates and/or manage their certificates with OpenSSL/LibreSSL, find useful information in [[#Importing an_Existing_Certificate|Importing an Existing Certificate]].
−
* Prepare a text file ''request.inf'' with the following content
 
  
−
;----------------- request.inf -----------------
+
== Creating or Renewing a Certificate ==
−
[Version]
+
Follow the below instructions to create or renew a certificate and import it into Windows' certificate store.
−
Signature="$Windows NT$"
 
−
 
−
[NewRequest]
 
−
; replace Subject attributes in the line below with real values
 
−
Subject = "CN=hostname, OU=Department, O=Organisation, L=Locality, S=State, C=Country"
 
−
KeySpec = 1
 
−
KeyLength = 2048
 
−
Exportable = TRUE
 
−
FriendlyName = hostname
 
−
MachineKeySet = TRUE
 
−
SMIME = Falsedg
 
−
PrivateKeyArchive = FALSE
 
−
UserProtected = FALSE
 
−
UseExistingKeySet = FALSE
 
−
ProviderName = Microsoft RSA SChannel Cryptographic Provider
 
−
ProviderType = 12
 
−
RequestType = PKCS10
 
−
KeyUsage = 0xa0
 
−
 
−
[EnhancedKeyUsageExtension]
 
−
; this is for Server Authentication
 
−
OID=1.3.6.1.5.5.7.3.1
 
−
 
−
[Extensions]
 
−
; If your client operating system is Windows Server 2008, Windows Server 2008 R2, Windows Vista, or Windows 7
 
−
; SANs can be included in the Extensions section by using the following text format. Note 2.5.29.17 is the OID for a SAN extension.
 
−
2.5.29.17 = "{text}"
 
−
_continue_ = "dns=hostname.local&"
 
−
_continue_ = "dns=mailstore&"
 
−
_continue_ = "ipaddress=172.20.13.16&"
 
−
;-----------------------------------------------
 
  
−
* Adjust the ''Subject'', ''FriendlyName'' and ''Extensions'' fields according to you infrastructure. Remove the entire ''[Extensions]'' section, if you do not need SANs. Save the file.
+
=== Generating a Certificate Signing Request (CSR) ===
 +
It is assumed that the following steps are carried out on the machine, where the certificate is actually going to be used by MailStore SPE.
  
−
<p class="msnote">'''Hint:''' An IP address as SAN  will not be accepted by official CAs.
+
* Prepare a text file <tt>request.inf</tt> with the following content:
 +
<pre>
 +
;----------------- request.inf -----------------
 +
[Version]
 +
Signature="$Windows NT$"
  
−
When there are any SANs defined, the CN in the ''Subject'' field will be ignored by clients, therefore you have to add all possible hostnames to the SAN extensions.</p>
+
[NewRequest]
 +
; replace Subject attributes in the line below with real values
 +
Subject = "CN=mailarchive.example.com, OU=Department, O=Organisation, L=Locality, S=State, C=Country"
 +
KeySpec = 1
 +
KeyLength = 2048
 +
Exportable = TRUE
 +
FriendlyName = mailarchive.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
  
−
* Open an elevated command prompt and navigate into the directory where the ''request.inf'' is stored.  
+
[Extensions]
 +
2.5.29.17 = "{text}"
 +
_continue_ = "DNS=mailarchive.example.com&"
 +
_continue_ = "DNS=archive.example.com&"
 +
_continue_ = "DNS=*.example.com&"
 +
</pre>
 +
* 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.
 +
* 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
  
−
''' Creating the CSR '''
+
=== Validating the Certificate Signing Request ===
−
certreq -new request.inf request.csr
+
To verify that the CSR is correct, execute the following command to display it in a human readable format:
  
−
''' Validating the CSR '''
 
 
  certutil -dump request.csr
 
  certutil -dump request.csr
  
−
* Submit the CSR to your CA. You will get a signed certificate in return.
+
=== Submitting the Certificate Signing Request ===
 +
Submit the CSR to your preferred 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.
  
−
''' Importing the certificate '''
+
<p class="msnote">'''Please note:''' Nowadays most CAs require the installation of intermediate CA certificates. Detailed information about the installation process of intermediate CA certificates is typically included in the electronic delivery of your certificate.</p>
−
certreq -accept certificate.cer
 
  
−
* Verify with ''certlm.msc'' or ''mmc'' that the certificate is imported properly in the hosts ''Personal'' store and that a matching private key can be found.
+
=== 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:
  
−
* [[Replace_Self-signed_SSL_Certificates|Replace]] the self-signed certificates in the ''Client Access Server''.
+
certreq -accept certificate.cer
  
−
External Links:
+
=== Verifying the Import ===
 +
* Log on as administrator to the server on which certificate has been imported.
 +
* 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.
  
−
[https://technet.microsoft.com/de-de/library/ff625722.aspx Microsoft Technet: How to Request a Certificate With a Custom Subject Alternative Name]
+
==== 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:
  
−
[https://technet.microsoft.com/en-us/library/dn296456.aspx Microsoft Technet: Certreq]
+
* Open an elevated PowerShell and execute the following command:
  
−
[https://technet.microsoft.com/en-us/library/cc732443.aspx Microsoft Technet: Certutil]
+
Get-ChildItem Cert:\LocalMachine\My | select Subject, Serialnumber, Thumbprint, HasPrivateKey
  
−
== Creating a self signed certificate ==
+
* 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.
  
−
The ''makecert.exe'' is included in the SPE's installation directory. It can be used to create self-signed certificats.
+
certutil -repairstore my SerialNumber
  
−
makecert.exe -r -pe -n "CN=hostname" -b 01/01/2000 -e 01/01/2036 -eku 1.3.6.1.5.5.7.3.1 -ss my -sr localMachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 -a sha1 -len 2048
+
=== Using the Certificate ===
  
−
Replace ''hostname'' with your hostname.
+
* [[Replace_Self-signed_SSL_Certificates|Replace]] the self-signed certificates in the ''Client Access Server''.
−
 
 
−
External Links:
 
  
−
[https://msdn.microsoft.com/en-us/library/bfsktky3.aspx Microsoft MSDN: makecert]
+
== 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''.
  
−
== Converting a PEM/CRT into a PFX container with OpenSSL ==  
+
=== 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 certificate is available in Windows' certificate store of the MailStore SPE computer, but stored on the file system instead.
  
−
When the CSR was created with OpenSSL, the private key is not stored in the hosts private key archive automatically. You have to merge private key, certificate and the certificate chain into one PFX container, and import this container into the host's personal certificate store.
+
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.
  
−
''' Merging the files '''
+
The following steps need to be executed to convert the certificate files into a PFX container with OpenSSL or LibreSSL:
−
openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt
 
  
−
''' Importing the certificate '''
+
* Copy the certificate, private key and the certificates of the certificate chain into the OpenSSL or LibreSSL directory.
−
  certutil -importpfx certificate.pfx
+
* Open an elevated command prompt and navigate to this directory.
 +
* Create the PFX container by executing the following command, adjust the file names if 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
  
−
== Private key of certificate is missing ==
+
=== Importing a PFX container ===
 +
* Open an elevated command prompt and navigate into the directory where the PFX container resides.
 +
* Enter the following command to import the certificate into the personal store of the machine account, adjust the certificate file name if necessary:
 +
certutil -importpfx -enterprise my certificate.pfx
 +
* Enter the password which is used to protect the PFX file.
 +
* Certutil shows a success message when the certificate was imported successfully.
  
−
Sometimes the matching private key cannot be found, then it is necessary to run the following command
+
== Weblinks ==
−
certutil -repairstore my ''SerialNumber''
+
* [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/certreq_1 Microsoft Technet: Certreq]
−
where ''SerialNumber'' is the serial number (not fingerprint) of the certificate to be repairred.
+
* [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/certutil Microsoft Technet: Certutil]
 +
* [https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/ff625722(v=ws.10) 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]

Latest revision as of 13:35, 6 November 2024

Although various methods exist to create and import SSL certificates, this task can be laborious on Windows servers where no certificate policy exists (i.e. standalone servers). This article describes how to manually create and verify a certificate signing requests (CSR) and import the certificate after the CSR has been signed by a certificate authority, using Microsoft's Certreq tool.

Service Providers who already possess certificates and/or manage their certificates with OpenSSL/LibreSSL, find useful information in Importing an Existing Certificate.

Creating or Renewing a Certificate

Follow the below instructions to create or renew a certificate and import it into Windows' certificate store.

Generating a Certificate Signing Request (CSR)

It is assumed that the following steps are carried out on the machine, where the certificate is actually going to be used by MailStore SPE.

  • Prepare a text file request.inf with the following content:
;----------------- request.inf -----------------
[Version]
Signature="$Windows NT$"

[NewRequest]
; replace Subject attributes in the line below with real values
Subject = "CN=mailarchive.example.com, OU=Department, O=Organisation, L=Locality, S=State, C=Country"
KeySpec = 1
KeyLength = 2048
Exportable = TRUE
FriendlyName = mailarchive.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=mailarchive.example.com&"
_continue_ = "DNS=archive.example.com&"
_continue_ = "DNS=*.example.com&"
  • 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.
  • 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. 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 most CAs require the installation of intermediate CA certificates. 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 as administrator to the server on which certificate has been imported.
  • 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.

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

  • Replace the self-signed certificates in the Client Access Server.

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 certificate is available in Windows' certificate store of the MailStore SPE computer, but 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 if 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 an elevated command prompt and navigate into the directory where the PFX container resides.
  • Enter the following command to import the certificate into the personal store of the machine account, adjust the certificate file name if necessary:
certutil -importpfx -enterprise my certificate.pfx
  • Enter the password which is used to protect the PFX file.
  • Certutil shows a success message when the certificate was imported successfully.

Weblinks

Retrieved from "https://help.mailstore.com/en/spe/index.php?title=Working_with_SSL_Certificates&oldid=2104"