Create Certificates for Securing Aternity Management Server, Data Warehouse Server, Aggregation Server, and Aternity Docker Components

This article explains how to create keys and certificates stored in Java keystore for securing Aternity Management Server, Data Warehouse Server, Aggregation Server, as well as Aternity Docker Components Server.

Once you have certificates and keys, you can configure SSL encryption (HTTPS). When you configure servers to use Secure Sockets Layer (SSL) encryption, this ensures that access to the server is secure and that data is protected.

Before you begin

  • Java keytool is a key and certificate management tool that is used to manipulate Java keystores, and is included with Java. Verify that the keytool is available on Aternity Management Server at [ATERNITY_HOME]\jre\bin.

  • (Optional) To avoid repeatedly entering the full path to the keytool utility, add the tool’s location to the Windows path, using command prompt:
    set PATH=%PATH%;[ATERNITY_HOME]\jre\bin
    For example:
    set PATH=%PATH%;D:\data\aternity\jre\bin
  • Make sure you have access to the organizational certificate signing web interface or that you have the contact details of the person responsible for certificates signing.

Procedure

  1. Step 1 Generate keypair into Java keystore (JKS)
    1. a On the Aternity Management Server, create a folder to hold all the files you will create in the following steps (for example, D:\certificates.
    2. b Generate a new keypair into a Java keystore by running the following command in the command prompt:
      keytool -genkeypair -keyalg RSA -alias [ALIAS] -keystore [KEYSTORE_NAME].jks -validity [DAYS]
            -keysize [KEY_LENGTH] -dname "CN=[COMMON_NAME], OU=[ORGANIZATIONAL_UNIT], O=[ORGANIZATION],
            C=[COUNTRY]" -ext SAN=dns:[FQDN]
      For example,
      keytool -genkeypair -keyalg RSA -alias example_alias -keystore example_keystore.jks -validity
            365 -keysize 2048 -dname "CN=example.aternity.com, OU=Aternity, O=Riverbed, C=US" -ext
            SAN=dns:example.aternity.com
      Parameter Description
      keyalg

      The encryption algorithm used for the private key encryption.

      alias

      A keystore file may contain multiple certificate keys. Each key entry must be assigned an alias parameter and can be referred to using this parameter. Make a note somewhere of the name defined in this command, as you may need it for further operations.

      keystore

      The target keystore name where the private key and certificates are stored. Created by running this command.

      validity

      The desired validity in days for the generated keypair.

      keysize

      The key length in bits. Unless explicitly stated or left empty, the default size 512 will appear. Values less than 2048 are not recommended because short keys are less secure.

      dname
      A set of parameters describing the server to be secured and the organization behind it
      • CN – Common Name: This value must match the URL address that users and Aternity components will use to access this server. For example, example.aternity.com.

      • OU – Organizational Unit: Enter the name of an organizational unit within the company

      • O – Organization Name: Enter the name of the company that owns that server

      • C – Country code: Enter a country code: Two letters abbreviation of the country name, for example, US for the United States.

      ext
      Additional attributes assigned to the certificate.
      • SAN – Subject Alternative Name: An extension allowing additional identities to be bound to the subject of the certificate. The dns prefix designates a DNS name. As with CN, the value must match the address users and other Aternity components will use to access this server. For example, SAN=dns:example.aternity.com

    3. c When prompted, define passwords for the keystore and alias. Make a note somewhere of both passwords, as you may need them for further operations.
      Note

      For each keystore (Aternity Management Server, or Data Warehouse Server, or Aggregation Server), the passwords for the keystore and the server certificate alias should match.

      A keystore file containing an unsigned certificate (public key) and a private keypair is now created. Verify that the keystore has been properly created in the predefined folder.

    4. d Verify that the keystore has been created in the required folder.
  2. Step 2 Create a certificate signing request (CSR) to send to a certificate authority (CA).
    1. a Generate a certificate signing request using the following command:
      keytool -certreq -keystore [KEYSTORE_NAME].jks -alias [ALIAS] -file [REQUEST_FILE_NAME].csr -dname "CN=[COMMON_NAME], OU=[ORGANIZATIONAL_UNIT], O=[ORGANIZATION], C=[COUNTRY]" -ext SAN=dns:[FQDN]
      For example,
      keytool -certreq -keystore example_keystore.jks -alias example_alias -file
            example_signing_request.csr -dname "CN=example.aternity.com, OU=Aternity, O=Riverbed, C=US"
            -ext SAN=dns:example.aternity.com
      Parameter Description
      alias

      A keystore file may contain multiple certificate keys. Each key entry must be assigned an alias parameter and can be referred to using this parameter. Make a note somewhere of the name defined in this command, as you may need it for further operations.

      keystore

      The target keystore where the private key and certificates are stored. Created by running this command.

      dname
      A set of parameters describing the server to be secured and the organization behind it
      • CN – Common Name: This value must match the address users and other Aternity components will use to access this server. For example, example.aternity.com.

      • OU – Organizational Unit

      • O – Organization Name

      • C – Country code: Two letters abbreviation of the country name, i.e. US for the United States

      ext
      Additional attributes assigned to the certificate.
      • SAN – Subject Alternative Name: An extension allowing additional identities to be bound to the subject of the certificate. The dns prefix designates a DNS name. As with CN, the value must match the address users and other Aternity components will use to access this server. For example, SAN=dns:example.aternity.com

      file

      The target certificate signing request created by running this command.

    2. b When prompted, enter the keystore password that you defined earlier.
    3. c Verify that the CSR has been created in the required folder.
  3. Step 3 Submit the CSR to a certificate authority (CA) to obtain a signed certificate.
    Note

    The exact procedure depends on the organization certificate authority and policies, so the steps below are general and may vary.

    1. a Submit the CSR created in the previous step to be signed by the organizational CA.

      You can submit it via web interface or send to the designated individuals.

    2. b Once submitted and signed by CA, receive the following:
      • Signed server certificate

      • Root CA certificate

      • Intermediate CA certificate(s): Depending on the organization policy, there may be one or more intermediate CA certificates in the server certificate’s trust chain.

    3. c Copy all certificates to the certificates folder created in step 1.
  4. Step 4 Import CA certificate(s) into Java keystore (JKS).
    1. a Import the CA certificate into the Java keysore using the following command:
      keytool -importcert -keystore [KEYSTORE_NAME].jks -alias [CA_ALIAS] -file [ROOT_CA_CERTIFICATE_NAME].crt
      For example:
      keytool -importcert -keystore example_keystore.jks -alias root_ca_alias -file example_root_ca.crt
      Parameter Description
      keystore

      The target keystore where the private key and certificates are stored. Created by running this command.

      alias

      Enter a unique alias for each certificate you are adding. Make sure it is different from alias you used for the server certificate in step 1.

      file

      The name of the CA certificate file being imported.

      Repeat for each CA certificate, starting with the root CA.

    2. b When prompted, approve trusting the CA certificate by entering yes.
    3. c Verify that the keystore containing the unsigned server certificate, the root CA certificate, and any intermediate CA certificates have been created.
  5. Step 5 Import the signed server certificate into JKS.
    1. a Import the signed server certificate by running the following command from the folder created in step 1.a (this will overwrite the unsigned certificate currently stored in the JKS):
      keytool -importcert -keystore [KEYSTORE_NAME].jks -file [SIGNED_SERVER_CERTIFICATE_NAME].crt -alias [ALIAS]
      For example:
      keytool -importcert -keystore example_keystore.jks -file signed_example_server_certificate.crt -alias example_alias
      Parameters Description
      alias

      A keystore file may contain multiple certificate keys. Each key entry must be assigned an alias parameter and can be referred to using this parameter. Make a note somewhere of the name defined in this command, as you may need it for further operations.

      Note

      alias must be identical to the defined earlier in this procedure.

      keystore

      The target keystore where the private key and certificates are stored. Created by running this command.

      file

      The name of the signed server certificate.

    2. b When prompted, enter the keystore password that you defined earlier.
  6. Step 6 Continue with setting an SSL encryption (HTTPS) for securing communication between servers.
  7. Step 7 In case you received the signed server certificate and its private key inside a PFX keystore (following your organization policy), export it to the JKS.
    1. a On the Aternity Management Server, create a folder to hold all the files you will create in the following steps (for example, D:\certificates.
    2. b (Optional) To avoid repeatedly entering the full path to the keytool utility, add the tool’s location to the Windows path, using command prompt: set PATH=%PATH%;[ATERNITY_HOME]\jre\bin

      For example: set PATH=%PATH%;D:\data\aternity\jre\bin

    3. c Import the signed certificate from the PFX keystore into a new Java keystore by running the following command:

      keytool -importkeystore -srckeystore [SOURCE_PFX_STORE].pfx -srcstoretype pkcs12 -destkeystore [DESTINATION_JKS].jks -deststoretype JKS -srcalias [SOURCE_ALIAS] -destalias [DESTINATION_ALIAS]

      This command creates the Java keystore file.

      Parameters Description
      importkeystore
      srckeystore

      Enter the name of the source keystore that contains the signed certificate.

      srcstoretype

      Enter pkcs12 as the source keystore type.

      destkeystore

      Enter JKS as the destination keystore type.

      srcalias

      Enter the alias for the relevant key entry in the source keystore.

      destalias

      Enter the desired alias for the key entry in the destination Java keystore.

      For example: keytool -importkeystore -srckeystore server_certificate.pfx -srcstoretype pkcs12 -destkeystore server_certificate.jks -deststoretype JKS -srcalias pfx_alias -destalias example_alias

    4. d When prompted, enter the password for the new Java keystore, and then enter it again for confirmation.
    5. e When prompted, enter the password for the source PFX keystore.

      A Java keystore with a signed server certificate and its associated private key is now created.

    6. f Continue with setting an SSL encryption (HTTPS) for securing communication between servers.