Setting up SSL for your Nodes

The Aspera Node API provides an HTTPS interface for encrypted communication between node machines (on Port 9092, by default). For example, if you are running the Faspex Web UI or the Shares Web UI on Machine A, you can encrypt the connection (using SSL) with your transfer server or file-storage node on Machine B. Enterprise Server nodes are preconfigured to use Aspera's default, self-signed certificate (aspera_server_cert.pem), located in the following directory:

/opt/aspera/etc/

About PEM Files: The PEM certificate format is commonly issued by Certificate Authorities. PEM certificates have extensions that include .pem, .crt, .cer, and .key, and are Base-64 encoded ASCII files containing "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" statements. Server certificates, intermediate certificates, and private keys can all be put into the PEM format.

To generate a new certificate, follow the instructions below.

  1. Generate a Private Key and Certificate Signing Request (CSR) using OpenSSL.
    In a Terminal window, run the following command (where my_key_name.key is the name of the unique key that you are creating and my_csr_name.csr is the name of your CSR):
    $ openssl req -new -nodes -keyout my_key_name.key -out my_csr_name.csr
  2. At the prompt, enter your X.509 certificate attributes.
    Important: The Common Name field must be filled in with the fully qualified domain name of the server to be protected by SSL. If you are generating a certificate for an organization outside the U.S., go to https://www.iso.org/obp/ui/, select Country codes, and click to view a list of two-letter ISO country codes.
    Generating a 1024 bit RSA private key
    ....................++++++
    ................++++++
    writing new private key to 'my_key_name.key'
    -----
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [US]:Your_2_letter_ISO_country_code
    State or Province Name (full name) [Some-State]:Your_State_Province_or_County
    Locality Name (eg, city) []:Your_City
    Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your_Company
    Organizational Unit Name (eg, section) []:Your_Department
    Common Name (i.e., your server's hostname) []:secure.yourwebsite.com
    Email Address []:johndoe@yourwebsite.com
    

    You are also prompted to input "extra" attributes, including an optional challenge password.

    Note: Manually entering a challenge password when starting the server can be problematic in some situations, for example, when starting the server from the system boot scripts. Skip entering a challenge password by pressing Enter.
    ...
    Please enter the following 'extra' attributes
    to be sent with your certificate request
    A challenge password []:
    An optional company name []:
    

    After finalizing the attributes, the private key and CSR are saved to your root directory.

    Important: If you make a mistake when running the OpenSSL command, you may discard the generated files and run the command again. After successfully generating your key and CSR, be sure to guard your private key, as it cannot be re-generated.
  3. If required, send the CSR to your Certifying Authority (CA).
    Once completed, you will have a valid, signed certificate.
    Note: Some certificate authorities provide a CSR generation tool on their website. For additional information, check with your CA.
  4. If required, generate a self-signed certificate.
    You may need to generate a self-signed certificate for the following reasons:
    • You don't plan on having your certificate signed by a CA.
    • You plan to test your new SSL implementation while the CA is signing your certificate.

    To generate a self-signed certificate through OpenSSL, run the following command:

    # openssl x509 -req -days 365 -in my_csr_name.csr -signkey my_key_name.key -out my_cert_name.crt

    This creates a certificate that is valid for 365 days.

  5. Create the .pem file.
    Note: Before overwriting the existing .pem file, be sure to back up this file as aspera_server_cert.old), in the following directory:
    /opt/aspera/etc/
    Copy and paste the entire body of the key and cert files into a single text file and save the file as aspera_server_cert.pem. The order of the text in the new .pem file depends on if you have individual certificate files or a bundle of certificates.

    Individual certificate files:

    1. The private key.
    2. The primary server's certificate.
    3. The intermediate certificates, if any (if more than one, begin with the least authoritative and proceed in ascending order).
    4. The root certificate.

    Bundle of certificates:

    1. The private key.
    2. The primary server's certificate.
    3. The entire bundle (as one file).

    For a certificate bundle, create a new file named aspera_server_cert.chain in the same directory as the .pem files. Copy and paste the root certificate into this file, followed by the bundle.

  6. Enable SSL options in aspera.conf.
    For information about enabling specific SSL protocols with <ssl_protocol> and enabling specific encryption ciphers with <ssl_ciphers>, see Configuring for the Node API.
  7. Restart the node service by running the following command:
    $ sudo /etc/init.d/asperanoded restart