Managing Java Trust Store and Key Stores

If you wish to enable secure communication to the VEP's REST server over HTTPS, you will need to provide a valid Java Key Store (.jks) file that contains the server's certificate file. You must also configure your system's Java global trust store file with your trusted certificate authority (CA) certificate file. This will allow the VEP HTTPS server accept only valid client's certificate (one that has been generated by your trusted CA).

In this tutorial I will provide a step-by-step guide to properly configure the Java global trust store file and generate a valid java key store file to be used with your VEP installation. We will assume you have a valid openssl and openvpn installations on your linux system.

  • install openvpn
  • locate easy-rsa directory
    $ locate easy-rsa
  • copy the easy-rsa directory somewhere in your home directory
  • change directory to easy-rsa/2.0/
  • modify vars file with correct country, province, city, org, email values. An example tail of vars file is given below:
    # These are the default values for fields
    # which will be placed in the certificate.
    # Don't leave any of these fields blank.
    export KEY_COUNTRY="FR"
    export KEY_PROVINCE="BRETAGNE"
    export KEY_CITY="Rennes"
    export KEY_ORG="INRIA-Myriads"
    export KEY_EMAIL="your-email@goes-here.com"
  • execute these commands next
    $ source ./vars
    $ ./clean-all
    $ ./build-ca
    These above steps will create your CA certificate.
  • next create the VEP rest-server's certificate (DO NOT FORGET to provide a password when prompted)
    $ ./build-key-server <server-name>
    Replace <server-name> above with the valid hostname of the machine where your server will be executed, example mydomain.com, localhost, etc.
  • change directory to keys inside easy-rsa/2.0/* folder, all the generated keys are stored here
  • combine the server's private key and the certificate file into a single .pfx file
    $ openssl pkcs12 -export -inkey <server-name>.key -in <server-name>.crt -out <server-name>.pfx -name default
    Make sure the <server-name> is the same as you used in the previous steps
  • Now create the rest-server java key store .jks file
    $ keytool -importkeystore -srckeystore <server-name>.pfx -srcstoretype pkcs12 -destkeystore VEPRestKeyStore.jks \
       -srcalias default -destalias <your-domain-name> -destkeypass <same-as-when-creating-the-server-key>
    It is important to use the exact same password for the keystore and the server-key otherwise the keytool will fail.
  • Now you must import your CA certificate in Java global trust store - this must be performed as root user
    • If you have multiple java runtimes installed, it is important to locate the default JRE
      $ java -version
      This will help you find the default JRE version and type. Next locate the jre/lib/security directory
      $ locate jre/lib/security
      change directory to the correct jre/lib/security folder corresponding to your default JRE setup as determined in the steps before
      # keytool -import -alias <your-CA-name> -file <ca.crt> -keystore cacerts -storepass changeit
      <ca.crt> is the CA's certificate file that was generated by openvpn in the beginning and can be found in easy-rsa/2.0/keys folder. By default the cacerts trust-store has password changeit, if you have changed it then replace it with the changed password.
  • Now that we have generated your own CA, and have generated the VEP Rest-Server's .jks keystore file, let us see how we can generate a client certificate signed by the same self-CA that was created using openvpn scripts
    • change directory to easy-rsa/2.0
      $ ./build-key <username>
      make sure you provide the correct username argument, this must match the user's account id in the VEP database exactly.
  • convert the client's certificate into a .pfx file for a standard browser (Chrome, Firefox, etc.) import
    $ openssl plcs12 -export -out <username>.pfx -inkey <username>.key -in <username>.crt -certfile <ca.crt>
    If any of the steps above asks you to enter passwords, then provide the appropriate passwords that you might have used while creating the CA certificate, or client certificates.

Now you can use the generated .jks files and the .pfx client certificates for VEP's secure HTTPS communication.