Understanding the private key for the SSL certificate

Applies to: VisualSVN Server 5.1 and later

VisualSVN Server supports secure connections over the HTTPS protocol (Hypertext Transfer Protocol Secure). To provide connectivity over HTTPS, VisualSVN Server needs the following:

• An SSL certificate configured and installed for VisualSVN Server,
• A private key that is associated with the installed SSL certificate.

The SSL certificate and the associated private key are used together to confirm the identity of the server and to encrypt the data sent over the network.

A private key is a secret value (a long random sequence of bits) stored on the server. The security of the HTTPS encryption depends on this value being known only to the server, and to no one else. You need a private key to create and to use SSL certificates. A private key associated with an SSL certificate is the specific key that was used to create this particular SSL certificate.

During the installation of VisualSVN Server, a private key for it is generated locally and is installed automatically, thereby allowing you to create SSL certificates and use them. It is also possible to generate and install a new private key for VisualSVN Server as described below.

Generating a new private key

The option to generate a new private key for VisualSVN Server is presented when you are creating a new SSL certificate using either one of the following wizards in the VisualSVN Server Manager console:

• Prepare certificate request (to obtain a certificate signed by a third-party Certificate Authority),
• Obtain certificate from Active Directory,
• Create self-signed certificate.

In these wizards, on one of the steps you will be prompted to select a private key that you want to use to create this new SSL certificate:

• Use existing private key. Use the existing private key (which is currently installed in VisualSVN Server) to create the new SSL certificate.
• Generate new private key. Generate a brand new private key and use it to create the new SSL certificate.

If you select the Generate new private key option, then, once you complete the installation of the newly created SSL certificate, the newly generated private key associated with this certificate will also be automatically installed. Until this new private key is installed, it is kept as a pending private key.

Pending certificate signing request and pending private key

As mentioned above, the newly generated private key is initially stored as a pending private key, until the installation of the associated SSL certificate is completed.

You cannot have more than one pending private key stored at the same time. If you already have a pending private key from an uncompleted certificate change procedure, and you attempt to generate a new private key again, you will see the following warning:

If you click Yes in this warning to generate a new private key again, the previously stored pending private key will be discarded and overwritten by the pending private key that you have generated now.

If through the Complete certificate request wizard you attempt to install an SSL certificate that is associated with a discarded pending private key, this action will fail with the following error:

This error occurs when the SSL certificate that you are trying to install matches neither the current pending private key nor the currently installed private key. If an SSL certificate is associated with a discarded pending private key, there is no way to install it, and you will have to restart the certificate creation and signing procedure from scratch to obtain a usable certificate.

Generating a new private key in PowerShell

As an alternative to the GUI-based approach described above, it is also possible to generate and install a new private key for VisualSVN Server through PowerShell, when you are configuring a new SSL certificate. This procedure involves three steps.

1. Create a new Certificate Signing Request (CSR) for a new SSL certificate by using the New-SvnServerCertificateRequest cmdlet. On this step, you can optionally generate a new private key for your VisualSVN Server by adding the -NewKeyPair parameter:

   New-SvnServerCertificateRequest -NewKeyPair

   With -NewKeyPair specified, the command generates a brand new private key and creates a CSR that is associated with this new private key, printing this CSR onto the screen. This newly generated private key is not installed yet and is stored as a pending private key, until you complete step 3 below. See the description of the New-SvnServerCertificateRequest command, for information on its other available parameters that configure the CSR.

   If you omit the -NewKeyPair parameter, this command instead creates and outputs a CSR associated with the current private key installed in your VisualSVN Server.

2. Get the CSR signed. You can do it by submitting the CSR created on step 1 to a Certificate Authority for signing. The Certificate Authority will send you back a signed SSL certificate. The signed SSL certificate is associated with the same private key as the CSR that it was created from.

3. Install the signed SSL certificate into your VisualSVN Server by using the Set-SvnServerConfiguration command with the -ServerCertificate parameter. For example, the following two commands will do this job:

   $cert=New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\server.cer")
   
   Set-SvnServerConfiguration -ServerCertificate $cert

   The first command parses the specified SSL certificate file and stores it as a certificate object into a temporary variable. In this first command, replace C:\server.cer with a path to your SSL certificate file that you want to install. The second command installs the certificate from the temporary variable.

   If the SSL certificate that you install here is associated with the new private key from step 1, this last command also automatically installs that associated new private key into your VisualSVN Server.

With one exception, the things described above in the Pending certificate signing request and pending private key section also apply to this PowerShell procedure. The one exception is that the New-SvnServerCertificateRequest -NewKeyPair command always generates a new private key without any warnings. If an older pending key exists, the command always discards it and overwrites it with the new one that it generates; for instance, this will occur, if you execute step 1 more than once before proceeding to steps 2 and 3.

Similarly, on step 3, the Set-SvnServerConfiguration command will succeed only if the SSL certificate matches either the stored pending private key or the current private key of your VisualSVN Server. Otherwise, the command will output an error:

If your SSL certificate that you want to install is associated with a discarded pending private key, you have to perform all 3 steps again to obtain a usable certificate.

See also

KB134: Configuring SSL Certificates for VisualSVN Server
KB165: Using VisualSVN Server PowerShell module