Setting Up SSL Encryption

www.altova.com Expand/Collapse All Print this Topic Previous Page Up One Level Next page

Home >  Server APIs: HTTP REST, COM/.NET, Java > HTTP REST Client Interface > Server Setup >

Setting Up SSL Encryption

If you wish to encrypt your RaptorXML+XBRL Server data transfers using the SSL protocol, you will need to:

 

Generate an SSL private key and create an SSL public key certificate file
Set up RaptorXML+XBRL Server for SSL communication.

 

The steps to do this are listed below.

 

This method uses the open-source OpenSSL toolkit to manage SSL encryption. The steps listed below, therefore, need to be carried out on a computer on which OpenSSL is available. OpenSSL typically comes pre-installed on most Linux distributions and on macOS machines. It can also be installed on Windows computers. For download links to installer binaries, see the OpenSSL Wiki.

 

To generate a private key and obtain a certificate from a certificate authority, do the following:

 

 

1.Generate a private key

SSL requires that a private key is installed on RaptorXML+XBRL Server. This private key will be used to encrypt all RaptorXML+XBRL Server data. To create the private key, use the following OpenSSL command:

openssl genrsa -out private.key 2048

 

This creates a file called private.key, which contains your private key. Note where you save the file. You will need the private key to (i) generate the Certificate Signing Request (CSR), and (ii) be installed on RaptorXML+XBRL Server.

 

 

2.Certificate Signing Requests (CSRs)

A Certificate Signing Request (CSR) is sent to a certificate authority (CA), such as VeriSign or Thawte, to request a public key certificate. The CSR is based on your private key and contains information about your organization. Create a CSR with the following OpenSSL command (which provides the private-key file, private.key, that was created in Step 1, as one of its parameters):

openssl req -new -nodes -key private.key -out my.csr

 

During generation of the CSR you will need to give information about your organization, such as that listed below. This information will be used by the certificate authority to verify your company's identity.

 

Country
Locality (the city where your business is located)
Organization (your company name). Do not use special characters; these will invalidate your certificate
Common Name (the DNS name of your server). This must exactly match your server's official name, that is, the DNS name client apps will use to connect to the server
A challenge password. Keep this entry blank!

 

 

3.Buy an SSL certificate

Purchase an SSL certificate from a recognized certificate authority (CA), such as VeriSign or Thawte. For the rest of these instructions, we follow the VeriSign procedure. The procedure with other CAs is similar.

 

Go to the VeriSign website.
Click Buy SSL Certificates.
Different types of SSL certificates are available. For RaptorXML+XBRL Server, Secure Site or Secure Site Pro certificates should be sufficient. EV (extended verification) is not necessary, since there is no "green address bar" for users to see.
Proceed through the sign-up process, and fill in the information required to place your order.
When prompted for the CSR (created in Step 2), copy and paste the content of the my.csr file into the order form.
Pay for the certificate with your credit card.

 

Allow time for obtaining a certificate

Obtaining public key certificates from an SSL certificate authority (CA) typically takes two to three business days. Please take this into account when setting up your RaptorXML+XBRL Server.

 

 

4.Receive public key from CA

Your certificate authority will complete the enrollment process over the next two to three business days. During this time you might get emails or phone calls to check whether you are authorized to request an SSL certificate for your DNS domain. Please work with the authority to complete the process.

 

After the authorization and enrollment process has been completed, you will get an email containing the public key of your SSL certificate. The public key will be in plain text form or attached as a .cer file.

 

 

5.Save public key to file

For use with RaptorXML+XBRL Server, the public key must be saved in a .cer file. If the public key was supplied as text, copy-paste all the lines from

 

--BEGIN CERTIFICATE--

 ...

--END CERTIFICATE--

 

into a text file that we will call mycertificate.cer.

 

 

6.Save CA's intermediate certificates to file

To complete your SSL certificate, you will need two additional certificates: the primary and secondary intermediate certificates. Your certificate authority (CA) will list content of intermediate certificates on its website.

 

Verisign's intermediate certificates for its Secure Site product: https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR1735

 

Copy-paste both intermediate certificates (primary and secondary) into separate text files and save them on your computer.

 

 

7.Optionally combine certificates in one public key certificate file

You now have three certificate files:

 

Public key (mycertificate.cer)
Secondary intermediate certificate
Primary intermediate certificate

 

You can integrate your intermediate certificates into your public key certificate if you like. How to do this is described below. (Alternatively, you can use the https.certificate-chain configuration file setting to specify the location of intermediate certificates.)

 

Each contains text blocks bracketed by lines that look like this:

--BEGIN CERTIFICATE--

 ...

--END CERTIFICATE--

 

Now copy-paste all three certificates into one file so that they are in sequence. The order of the sequence is important: (i) public key, (ii) secondary intermediate certificate, (iii) primary intermediate certificate. Ensure that there are no lines between certificates.

--BEGIN CERTIFICATE--

public key from mycertificate.cer (see Step 5)

--END CERTIFICATE--

--BEGIN CERTIFICATE--

secondary intermediate certificate (see Step 6)

--END CERTIFICATE--

--BEGIN CERTIFICATE--

primary intermediate certificate (see Step 6)

--END CERTIFICATE--

 

Save the resulting combined certificate text to a file named publickey.cer . This is the public key certificate file of your SSL certificate. It includes your public key certificate as well as the complete chain of trust in the form of the intermediate certificates that were used by the CA to sign your certificate.

 


© 2019 Altova GmbH