Requesting and creating certificates

Follow the instructions in this section to obtain a certificate from a trusted certificate authority or to generate your own self-signed certificate for local use or testing purposes. These instructions apply to HTTPS applications and xfServer, xfServerPlus, and SQL OpenNet encryption.

Some of these instructions require the openssl utility, even though OpenSSL is (as of version 12) not used by Synergy encryption features on Windows; the files created with these procedures should continue to work with Schannel.

This topic includes the following sections:

Requesting a certificate from a certificate authority

Exporting and importing certificates in Windows

Creating a local certificate authority

Customizing the configuration files for OpenSSL

Requesting a certificate from a certificate authority

The instructions below explain how to use OpenSSL to create a certificate request file, which can be used to obtain a certificate from a trusted certificate authority so your server or client can be authenticated. This procedure can be used when developing an HTTPS server (or authenticated client), as well as for xfServer, xfServerPlus, and SQL OpenNet encryption.

On Windows, you can create a certificate request file using Microsoft Management Console instead of OpenSSL. For instructions, see Create a Certificate Request using Microsoft Management Console (MMC) or How to generate Certificate Signing Request using Microsoft Management Console (MMC) on Windows 2012. Once you generate the request file, send it to a public certificate authority.

1.

Use the openssl utility to create a certificate request and key file. The syntax is

openssl req -out cert_file [-keyout key_file] -newkey rsa:bits -config config_file [-nodes]

where cert_file is the name of the file to write the certificate request to, key_file is the name of the file to write the private key to, bits is the size in bits of the new RSA private key, and config_file is the name of your configuration file. (See Customizing the configuration files for OpenSSL for more information.) If the -keyout option is not specified, the private key filename specified in the configuration file is used as key_file. If you are requesting this certificate for use with SQL OpenNet data packet encryption, you may need to include the -nodes option; else, omit it.

The example below creates a new certificate request file, testreq.pem, and a new private RSA key file, testkey.pem, using configuration file openssl.cfg (which is a sample distributed with OpenSSL). The new private key will be 2048 bits. The certificate request file will contain the country, state, city, organization, department, and common name and email address of the requester.

openssl req -out testreq.pem -keyout testkey.pem -newkey rsa:2048 -config openssl.cfg

2.

Send the certificate request file generated in step 1 to a public certificate authority, such as VeriSign or Thawte, along with any necessary fees.

The certificate authority will send back a certificate that can be used to authenticate a server or client.

Exporting and importing certificates in Windows

One way to get a list of trusted Certificate Authorities is to export it from Microsoft Windows, which maintains its own list. For convenience, you can use this list as a CA file in the openssl utility or for the CA_file argument in the Synergy HTTP document transport API routines.

Exporting certificates

To export Certificate Authorities for use with OpenSSL or the Synergy HTTP document transport API,

1.

Open the Windows Control Panel and select Internet Options.

2.

Select the Content tab and click the Certificates button.

3.

Select the Trusted Root Certification Authorities tab.

4.

Select all of the certificates in this dialog box and click the Export button.

5.

Follow the Certificate Export Wizard to create a .p7b file.

6.

Use the openssl utility to convert the file to .pem format:

openssl pkcs7 -inform DER -outform PEM -in filename.p7b -out filename.pem -print_certs

Filename.pem can now be specified in the openssl utility or as the CA_file argument in the Synergy HTTP document transport API.

You can also export an individual certificate for use by vtxnetd or rsynd on a Unix or OpenVMS server, or as the cert_file argument in the HTTP document transport API routines on Unix or OpenVMS. To do this, follow the steps above, but in step 3 you will likely need to select another tab, such as Intermediate Certification Authorities or Personal, to find the certificate you need. Then, in step 4, select the certificate to export.

Importing certificates

You can import individual certificates or Certificate Authorities into the store on Windows. If you import an individual certificate, you can use its name or thumbprint in place of a .pem file anywhere you need to specify a certificate in a Synergy product on Windows (as described in Windows Certificate Store specification).

• If you want to add a new Trusted Root Certification Authority so that a Windows client can validate a server certificate, you can follow steps 1 through 3 above, then click the Import button and follow the Certificate Import Wizard.
• If you want to add a certificate for use by a server, use the Windows Certificate utility as described in the steps below. (Accessing a certificate from the certificate store requires certain permissions to be set, which can be managed only through this utility.) These instructions assume that you’re importing a .pfx file generated using the instructions in Creating a local certificate authority using OpenSSL (Windows and Unix). If you are importing a client or server certificate, a .pem file (containing both certificate and private key) can’t be used because the key won’t be imported, which will result in a SEC_E_NO_CREDENTIALS error when attempting to use it. You’ll need to convert the .pem file to a .pfx file and then import the .pfx:

openssl pkcs12 -inkey servercertkey.pem -in servercert.pem -export -out server.pfx 

1.

Open a Run dialog (Windows key + R) and type certlm.msc to open the Windows Certificate Manager for the local computer.

2.

In the left page, navigate to the Personal folder.

3.

Select Action > All Tasks > Import to launch the Certificate Import Wizard.

4.

Follow the steps in the Wizard and select the file you want to import as a trusted CA.

5.

If prompted, enter a password. (This is the password specified in step 9 in Creating a local certificate authority using OpenSSL (Windows and Unix).)

6.

On the Certificate Store screen, you can typically select “Automatically select the certificate store based on the type of certificate.” If you're importing a .pfx file created using the steps in Creating a local certificate authority using OpenSSL (Windows and Unix), this option should automatically put the certificate in Personal and the CA in Trusted Root Certification Authorities. Alternatively you can select “Place all certificates in the following store” and then specify the store to use, especially if you’re importing a single certificate (or multiple certificates that belong in the same store).

7.

When you’ve completed the Wizard, refresh the certlm app (with “Certificates - Local Computer” highlighted, select Action > Refresh, or click the Refresh toolbar button) and verify that the new certificate is listed.

8.

Double-click on the new certificate in the list to display the Certificate dialog, and then go to the Certification Path tab to see the status. If you didn’t import the CA that issued the certificate (or if you imported it to Intermediate Root Certification Authorities instead of Trusted Root Certification Authorities) the certificate chain may show warnings or errors.

9.

Close the Certificate window, but leave the new certificate selected in the list. The last step is to set permissions.

10.

Select Action > All Tasks > Manage Private Keys to display the Permissions dialog.

11.

Click the Add button, type “Everyone” in the “Enter the object names to select” field, and click OK.

12.

Verify that Everyone has at least Read permission, then click OK to apply the changes and close the dialog.

Creating a local certificate authority

If you want to test your HTTPS, xfServerPlus, or SQL OpenNet application locally, without going through a public certificate authority, you can establish a local certificate authority. In the actual production world, of course, you would use a public CA, such as VeriSign or Thawte. For xfServer, you may want to use a local certificate authority instead of a public certificate for both testing and production; because xfServer uses a proprietary protocol to transmit data, a public certificate may not provide any benefit over a local certificate.

There are many approaches you can take to generate a local certificate authority and certificate. We document two such approaches below, one using PowerShell and the other using OpenSSL.

Creating a local certificate authority using PowerShell (Windows)

This is the recommended approach to creating a certificate for use on Windows because it requires fewer steps than the OpenSSL method, and it automatically installs everything into your system’s local Certificate Store. If you need to create a .pem file for use on Unix or OpenVMS (or for older versions of Synergy on Windows that required OpenSSL), you can still use this method, but you’ll need to export the certificate (see Exporting certificates) when you’re done.

1.

Open an admin PowerShell window.

2.

Create a local certificate authority:

$rootcert = New-SelfSignedCertificate -certstorelocation cert:\LocalMachine\My -dnsname "CA_name" 
-KeyUsage CertSign,CrlSign,DigitalSignature

where CA_name is the common name you want to use for the certificate authority.

This command will generate a certificate for the CA and put it in both the Personal area of the Certificate Store and the $rootcert variable for use in subsequent commands. You can echo this variable to verify the command’s success and see details such as the thumbprint for the certificate, for example:

echo $rootcert

PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My
Thumbprint                                Subject
----------                                -------
0BE63E5B20BE39FE1C7FA92FF9D66861EAB15123  CN=MyCA

If you close this PowerShell window but want to use $rootcert later on, you can set the variable again by running the following command (replacing thumbprint with the actual thumbprint):

$rootcert = Get-ChildItem -Path cert:\LocalMachine\My\thumbprint

3.

Add the CA to the Trusted Root Certification Authorities store:

$store = new-object System.Security.Cryptography.X509Certificates.X509Store([System.Security.Cryptography
  .X509Certificates.StoreName]::Root,"LocalMachine")
$store.open("MAXAllowed")
$store.add($rootcert)
$store.close()

4.

Use the CA to sign a new certificate:

$cert = New-SelfSignedCertificate -DnsName "common_name" -CertStoreLocation "Cert:\LocalMachine\My" 
  -KeyAlgorithm RSA -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider"  
  -KeySpec KeyExchange -Signer $rootcert

Where common_name is the name you want to use for this certificate. This will typically be “localhost” or the name of the server that will be using this certificate. Wildcards can be used to match multiple servers on the same domain. You can specify one or more alternate names in a comma-separated list following the common name, for example:

New-SelfSignedCertificate -DnsName "*.mydomain.loc", "AltName1", "AltName2"... -CertStoreLocation ...

As with $rootcert, you can echo $cert to verify details, including the thumbprint.

5.

To use the certificate, users will need to have Read permissions for the Private Key (by default, only Administrators and related accounts have Read permissions). You can add permissions using the management console as described in Importing certificates, or you can use PowerShell to set permissions. The example below sets the GenericRead permission for the Everyone group. You can modify the $access line to change the permissions or target. (These steps are adapted from https://stackoverflow.com/questions/425688/how-to-set-read-permission-on-the-private-key-file-of-x-509-certificate-from-ne.)

$mystore = New-Object System.Security.Cryptography.X509Certificates.X509Store("My","LocalMachine")
$mystore.Open("ReadWrite")
$csp = New-Object System.Security.Cryptography.CspParameters($cert.PrivateKey.CspKeyContainerInfo.ProviderType, 
  $cert.PrivateKey.CspKeyContainerInfo.ProviderName, $cert.PrivateKey.CspKeyContainerInfo.KeyContainerName)
$csp.Flags = "UseExistingKey","UseMachineKeyStore"
$csp.CryptoKeySecurity = $cert.PrivateKey.CspKeyContainerInfo.CryptoKeySecurity
$csp.KeyNumber = $cert.PrivateKey.CspKeyContainerInfo.KeyNumber
$access = New-Object System.Security.AccessControl.CryptoKeyAccessRule("Everyone","GenericRead","Allow")
$csp.CryptoKeySecurity.AddAccessRule($access)
$rsa2 = New-Object System.Security.Cryptography.RSACryptoServiceProvider($csp)
$mystore.Close()

6.

To verify that the certificate was created and installed correctly, run certlm.msc. Go to Personal > Certificates in the left pane, click the refresh button to ensure that the list is up to date, and verify that the list contains a certificate that’s “Issued To” the common name you provided in step 4 and “Issued By” the common name you provided in step 1. Double-click on this certificate and go to the Certification Path tab to verify the certificate status. You can also look at the Details tab to verify the alternative names and thumbprint for the certificate.

In addition to the certificate itself, certlm should show two copies of the CA: one in Personal and the other in Trusted Root Certification Authorities. If you’re using the HTTP document transport API on a separate client machine and want the client to validate the server certificate, you can export this CA and import it into Trusted Root Certification Authorities on the client machine. Then, specify the keyword “cert_store” for the CA_file argument in API calls on the client.

Creating a local certificate authority using OpenSSL (Windows and Unix)

In this procedure, you’ll use the openssl utility to create a local CA file and then use it to generate a certificate.

On Windows, perform this procedure from an administrator command prompt. If you don’t, you may see the error “unable to write ‘random state’.”

These examples assume that the CA directory structure is already set up and the relevant files already exist. This is required if you use the “openssl ca” option in step 5. For the example configuration file (caopenssl.cfg), you would need subdirectories named certs, newcerts, and private; an empty index.txt file; and a file named serial containing “01”. This sample configuration file is included in Customizing the configuration files for OpenSSL.

1.

Before we can begin issuing certificates with our local CA, it needs a certificate of its own, so we’ll create a self-signed root certificate. The req command below is used to create the certificate request file rootreq.pem and private key file rootkey.pem. The key will be 2048 bits and the configuration file used will be caopenssl.cfg. If you are creating this certificate for use with SQL OpenNet data packet encryption, include the -nodes option; otherwise, omit it.

openssl req -out rootreq.pem -keyout rootkey.pem -newkey rsa:2048 -config caopenssl.cfg [-nodes]

(When prompted to “Enter Pem Pass Phrase,” enter the pass phrase, or password, that will later be required to access the certificate, and then enter it a second time to confirm when prompted. You can later remove this pass phrase if you don’t want to be prompted for it each time you access the certificate; see step 6. You may also be prompted for other information that will be incorporated into the certificate request; see Customizing the configuration files for OpenSSL for more information. )

2.

Next, the x509 command with the -req option is used to read the rootreq.pem file created above and create a root certificate in the rootcert.pem file. The -signkey option causes rootreq.pem to be self-signed using the private key rootkey.pem. The configuration file, caopenssl.cfg, contains certificate extensions to use. If -extfile is not specified, no extensions are added to the certificate.

openssl x509 -req -in rootreq.pem -out rootcert.pem -signkey rootkey.pem -extfile caopenssl.cfg

3.

(Optional) The following cat command simplifies things for testing purposes. It concatenates the certificate file (rootcert.pem) and the key file (rootkey.pem) to yield a concatenated file called root.pem. This file will be used when signing certificates in step 5.

cat rootcert.pem rootkey.pem > root.pem

On Windows, use the type command instead:

type rootcert.pem rootkey.pem > root.pem

4.

Create a certificate request and key file for your test program. This uses the same openssl req syntax as above. We name the certificate request testreq.pem and the key file testkey.pem. Once again, you may be prompted for additional information.

openssl req -out testreq.pem -keyout testkey.pem -newkey rsa:2048 -config caopenssl.cfg

5.

Create the certificate requested in the previous step and sign it using your local CA. In most cases, you can use either the openssl ca command or the openssl x509 command, but for xfServerPlus encryption, you must use x509.

The ca command is a minimal CA application. In the example below, testreq.pem is the file containing the certificate request to be signed by the local CA, testcert.pem is the file to return signed certificates to, and caopenssl.cfg is the configuration file.

openssl ca -in testreq.pem -out testcert.pem -config caopenssl.cfg

Alternatively, you could use the x509 command, which is a multi-purpose certificate utility. When the -CA option is present, the x509 command behaves like a minimal CA application. In the example below, testreq.pem is the file containing the certificate request to be signed by the local CA, -extfile adds certificate extensions from the configuration file caopenssl.cfg, root.pem is the CA certificate to be used for signing, CAkey is the private key to sign the certificate with, and testcert.pem is the file to return signed certificates to. (If the -CAkey option is not specified, it is assumed that the CA private key is present in the CA certificate file.) The -CAcreateserial option creates the CA serial number file if it does not exist. Future signing requests for this local CA should use -CAserial root.srl so the serial number can be incremented.

openssl x509 -req -in testreq.pem -extfile caopenssl.cfg -CA root.pem -CAkey root.pem 
-out testcert.pem -CAcreateserial 

6.

If any encryption options are set, a pass phrase will be prompted for whenever the key file is accessed. If you want to remove the pass phrase from an RSA private key, use the openssl rsa command. For example,

openssl rsa -in testkey.pem -out testkeyout.pem

where testkey.pem is the file containing the private key and testkeyout.pem is the file to write the updated key to. If you are using a concatenated certificate and key file, after removing the pass phrase, you must reconcatenate the two files.

7.

Concatenate the certificate (testcert.pem) and key file (testkeyout.pem, assuming you removed the pass key in step 6; otherwise, this would be testkey.pem). This step is required for xfServer and xfServerPlus encryption but optional for HTTPS. Do not do this for SQL OpenNet, where these files must remain separate. (For xfServer and xfServerPlus, you may want to name this file rsynd.pem; if you then put it in DBLDIR, it will be used by default.) For example,

cat testcert.pem testkeyout.pem > certkey.pem

On Windows, use the type command instead:

type testcert.pem testkeyout.pem > certkey.pem

8.

When you are done creating the files, put them in the appropriate places for your application. Typically, clients validate the server, so you would put the certificate and key files (or the concatenated certkey.pem file) on the server and the rootcert.pem file on the client.

9.

If you want to import this certificate into the Windows Certificate Store, first generate a .pfx file:

openssl pkcs12 -inkey testkeyout.pem -in testcert.pem -certfile rootcert.pem -export -out testcert.pfx

When prompted, enter and verify a password. (It doesn’t have to be the same one you used when generating the certificate, but that might make it easier to remember). Import this file (using the password again) to add both the certificate and CA to the appropriate stores.

Customizing the configuration files for OpenSSL

You’ll probably want to customize your own configuration file (for example, with your own company name and email address, number of days to certify for, etc.) and use that file to create the certificate or certificate request. To specify a configuration file in the openssl utility, use the -config option.

If “prompt = yes” is set in the configuration file, you'll be prompted for information such as the common name, state or province, etc. These fields will be left blank if there’s no default for them and you do not enter a value. (A value must be provided for at least one of them, or the file will not be created.) You may find it more efficient to include the prompted information in the configuration file (in the section labeled “[ req_distinguished_name ]”) and then set “prompt = no” (just above that section).

If you are using this configuration file with an xfNetLink .NET application, the xfServerPlus host name (as it is passed in the connect() method) must match either the common name or an alternate for the certificate. See the important note above. See Synergex KnowledgeBase article 2375 for additional information on this issue. To specify individual server names in the config file, see the example in the [alt_names] section below.

The following caopenssl.cfg file is used in the examples in Creating a local certificate authority.

####################################################################
[ ca ]
default_ca      = CA_default    # The default ca section

####################################################################
[ CA_default ]
dir             = . # Where everything is kept
certs           = $dir/certs    # Where the issued certs are kept
crl_dir         = $dir/crl      # Where the issued crl are kept
database        = $dir/index.txt # Database index file
new_certs_dir   = $dir/newcerts # Default place for new certs
certificate     = $dir/rootcert.pem # The CA certificate
serial          = $dir/serial # The current serial number
crl             = $dir/crl.pem # The current CRL
private_key     = $dir/root.pem # The private key
RANDFILE = $dir/private/.rand # Private random number file

x509_extensions = certificate_extensions # Extensions to add to the cert

# Extensions to add to a CRL. 
# crl_extensions = crl_ext

default_days     = 365 # How long to certify for
default_crl_days = 180 # How long before next CRL
default_md       = md5 # which md to use
preserve         = no # keep passed DN ordering

# A few different ways of specifying how similar the request should look.
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that.
policy          = policy_match
			
# For the CA policy
[ policy_match ]
commonName      = supplied
stateOrProvinceName = supplied
countryName     = supplied
emailAddress    = supplied
organizationName = supplied
organizationalUnitName = optional

# For the 'anything' policy
# At this point, you must list all acceptable 'object' types
[ policy_anything ]
countryName             = optional
stateOrProvinceName     = optional
localityName            = optional
organizationName        = optional
organizationalUnitName  = optional
commonName              = supplied
emailAddress            = optional

[ certificate_extensions ]
basicConstraints = CA:false
subjectAltName = @alt_names

[ alt_names ]
DNS.1	= myserver
DNS.2	= anotherserver

[ req ]
default_bits    = 2048
default_keyfile = rootkey.pem
default_md      = md5

prompt = yes 
distinguished_name = req_distinguished_name
x509_extensions = root_ca_extensions

[ req_distinguished_name ]
commonName = Common Name (typically, the server name) 
commonName_default = localhost
stateOrProvinceName = State or Province Name
stateOrProvinceName_default = California
countryName = Country Name
countryName_default = US
emailAddress = Email Address
emailAddress_default = jane.smith@MyCompany.com
organizationName = Organization Name
organizationName_default = MyCompany
organizationUnitName = Organization Unit Name

[ root_ca_extensions ]
basicConstraints = CA:true