Implementing Secure Sockets Layer (SSL) Encryption

AccuRev supports the use of the Secure Sockets Layer protocol to provide encrypted communication between AccuRev clients and servers. The implementation of this protocol is managed through the use of SSL certificates. Communication between AccuRev servers and clients depends on an agreement (or handshake) between the AccuRev client and server that confirms a pairing of a public key and a private key.

In general, to configure SSL client-server communications, the AccuRev administrator must take the following actions:

• Generate a private key.
• Obtain an SSL certificate.
• Enable SSL on the AccuRev server.

Each of these steps is described in more detail in the following sections.

In this topic:

Generating a Private Key

You can use an SSL toolkit to generate a private key. When generating a private key, keep in mind the following points:

• AccuRev supports the use of RSA private keys
• AccuRev does not support the use of password-protected private keys
• AccuRev expects the private key file to have a .pem file extension (*.pem)
• AccuRev recommends that you generate a private key that is at least of 1024-bit strength

Once you have generated a private key, you can place the private key file anywhere on the server machine.

Back to top

Obtaining an SSL Certificate

Once you have generated a private key, you can obtain an SSL certificate. There are two ways to obtain an SSL certificate:

• Submit a request for an SSL certificate signed by a trusted authority (either by a trusted authority or by an intermediary)
• Create a self-signed certificate

AccuRev expects the SSL certificate file to have a .crt extension (*.crt).

When obtaining an SSL certificate, keep in mind that the same certificate can be used for multiple computers or computer names as long as they are specified in the Subject Alternate Name (SAN) field of the certificate. Once you have obtained an SSL certificate, you can place the SSL certificate file anywhere on the server.

AccuRev supports the use of both self-signed and trusted certificates. Regardless of which type of certificate you use, AccuRev prompts the user to accept the certificate the first time the user attempts to connect to an AccuRev server that has been SSL-enabled. If the user then accepts the certificate, the certificate is downloaded from the server to the client and stored in the user’s profile directory which is, by default, the .accurev directory. (The location of the user’s profile directory is determined by the current setting of the USERPROFILE environment variable in Windows and UNIX while, on Linux platforms, the location is in the /home directory.) The user can then connect to that server in future sessions without being prompted to accept that certificate again, unless the certificate expires or SSL is disabled on the server. If, however, the user should attempt to connect to a different AccuRev server that has been SSL-enabled, the user is also prompted to accept the certificate from that server.

Considerations for Using Trusted Certificates

If you are using an SSL certificate from a trusted authority, you need to include the actual certificates in the certificate chain. You do this by appending intermediate and root certificates to the trusted SSL certificate as described here and as shown in the following example.

When adding intermediate and root certificates, note the following:

• The trusted authority's certificate must be the first one in the certificate file, followed by all intermediate certificates, and ending with the root certificate.

• Each certificate must be in Base64 encoded format (that is, PEM format).

• Each certificate must be preceded with ——-BEGIN CERTIFICATE——- and followed with
  ——-END CERTIFICATE——- on their own lines. These demarcations are present in each certificate and should not be removed.

• When editing the certificate file, make sure the editor you use recognizes non-standard characters like UNIX end-of-line characters. When you are done appending intermediate and root certificates, the format of your certificate file should resemble that shown in the following example.

Back to top

Enabling SSL Encryption on the AccuRev Server

After you have obtained an SSL certificate, ensure that you have placed both the private key file and the SSL certificate file in any location on the AccuRev server before attempting to enable SSL encryption.

To enable SSL encryption on an AccuRev server, add the following three parameters to the acserver.cnf file:

• SSL_ENABLED = TRUE

  Enable the server for SSL encryption by setting the SSL_ENABLED parameter to TRUE.

• SSL_CERTIFICATE = C:\Program Files (x86)\AccuRev\bin\ServerCert\AccuRev.crt

  In this example, C:\Program Files (x86)\AccuRev\bin\ServerCert\AccuRev.crt represents the absolute path to the server's certificate file, AccuRev.crt. This path name cannot contain quotes.

• SSL_PRIVATE_KEY = C:\Program Files (x86)\AccuRev\bin\ServerCert\AccuRev.pem

  In this example, C:\Program Files (x86)\AccuRev\bin\ServerCert\AccuRev.pem represents the absolute path to the server's private key file, AccuRev.pem. This path name cannot contain quotes.

After editing the acserver.cnf file, you must restart the AccuRev server to complete the process of encrypting communication between the server and its clients.

Back to top

Managing SSL

The following sections describe methods of managing the process of SSL encryption in AccuRev.

Using the —thumbprint Option

In public key encryption, a certificate's thumbprint (also known as a "fingerprint") is the SHA1 hash of the binary representation of the certificate converted to a hexadecimal string; it is this string that is used to authenticate a longer public key. The —thumbprint option allows you to specify the certificate's thumbprint which, if it matches that of the SSL certificate on the AccuRev server, allows the certificate to be accepted automatically. This option is available for both the enable_ssl command and the get_certificate command. This feature is particularly useful in situations where a user is not present to accept an SSL certificate.

The —thumbprint option can be used to enable SSL on unattended machines by using a script that executes a command, for example, such as the following:

For more information about the thumbprint command, refer to the descriptions of the get_certificate and enable_ssl commands in the AccuRev CLI Help.

Implementing SSL for Replicas

If replicas are being used, SSL encryption must be enabled on all machines. This means that:

• The master server must be SSL-enabled
• All clients must be SSL-enabled
• All replicas must be SSL-enabled as both a client (to the master server) and as a server (to all clients)

Replacing an Expired Certificate

If an SSL certificate expires, the AccuRev administrator must obtain a new SSL certificate. The existing private key can be used to obtain a new SSL certificate as long as its security has not been compromised. Otherwise, the administrator can generate a new private key and use that to obtain a new SSL certificate.

If the certificate name or location on the server has changed, the SSL_CERTIFICATE parameter of the acserver.cnf file must be updated to reflect the new file name or file path. Likewise, the SSL_PRIVATE_KEY parameter of the acserver.cnf file must be updated if the private key file name or location has been changed.

Disabling SSL Encryption on the AccuRev Server

To disable SSL encryption on the server, set the SSL_ENABLED parameter to FALSE in the acserver.cnf file:

SSL_ENABLED = FALSE

You could also delete this parameter or comment it out to disable SSL encryption on the server.

After editing the acserver.cnf file, you must restart the server to complete the process of disabling SSL.

When an SSL-enabled client attempts to connect to this server, the user is prompted to disable SSL on the client or exit the interface.

Back to top