Page tree
Skip to end of metadata
Go to start of metadata

Overview

The AIE Administrator runs within a Jetty webserver instance. The following steps are required to configure Jetty for SSL:

Step 1: Obtain a public/private key pair and X.509 certificate, or generate them using the keytool and openssl utilities.
Step 2: Optionally purchase a certificate from a trusted certificate authority.
Step 3: Load the keys and the certificates into a Java Secure Socket Extension (JSSE) Keystore.
Step 4: Configure a JsseListener with the location and passwords for the keystore.  

View incoming links.

Step 1: Keys and Certificates

The simplest way to generate keys and certificates is to use the keytool utility that comes with the Java Development Kit (JDK), as it generates keys and certificates directly into the keystore (see Step 1a).

Attivio recommends importing your custom certificates into a copy (copied to the resources directory your local project) of the default attivio.ks keystore provided in the installation rather than creating your own. See Enabling SSL HTTPS for AIE Web Applications for an example of how this file is referenced.

If you already have keys and certificates, please go to Step 3 to load them into a JSSE key store.

The commands below only generate minimal keys and certificates. You should read the full manuals of the tools you are using if you wish to specify:

  • Key size
  • Certificate expiry
  • Alternate security providers

Step 1a: Generating a certificate with the Java keytool

The following command will generate a public/private key pair and a certificate directly into a JKS-format keystore:

Linux Shell
<INSTALL_DIR>/jre/bin/keytool -keystore conf/attivio.ks -alias admin -genkey -keyalg RSA

This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the server's fully-qualified hostname at the "first and last name" prompt By default, the certificate authorizes one domain only (e.g., my.company.com), but you can configure a wildcard certificate (e.g., *.company.com) to authorize multiple subdomains of the primary domain.

For example:

/opt/attivio/platform/jre/bin/keytool -keystore conf/attivio.ks -alias admin -genkey -keyalg RSA
Enter keystore password: attivio
Re-enter new password: attivio
What is your first and last name?
  [Unknown]:  my.company.com
What is the name of your organizational unit?
  [Unknown]:  My Organization
What is the name of your organization?
  [Unknown]:  My Company Name
What is the name of your City or Locality?
  [Unknown]:
What is the name of your State or Province?
  [Unknown]:
What is the two-letter country code for this unit?
  [Unknown]:
Is CN=my.company.com, OU=My Organization, O=My Company Name,
L=Unknown, ST=Unknown, C=Unknown correct?
  [no]:  yes

Enter key password for <admin>
        (RETURN if same as keystore password): password
Re-enter new password: password

You now have the minimal requirements to run an SSL connection and could proceed directly to Step 4 to configure an SSL connector. However the certificate you have generated will not be automatically trusted by the browser and the user will be prompted to this effect. This is often sufficient for testing, but most public sites will want to follow the steps in Step 2a to obtain a certificate trusted by most popular browsers.

Step 1b: Generating Keys and Certificates with openssl

OpenSSL Requirements

In order to run the next steps you will need the OpenSSL command-line tools. To install these you can use the following commands:

Linux
To install OpenSSL on Redhat or CentOS Linux, run the command below:

sudo yum install openssl

Windows
To install OpenSSL on windows you will have to download or build a binary distribution of OpenSSL for Windows. You can find binary distributions on the OpenSSL.org binary distributions page or the source can be downloaded from the OpenSSL.org source distribution page. When using the openssl commands below make sure to point to your OpenSSL install or make sure that the binary directory of that install is included in your PATH environment variable so that you can run openssl from a Command Prompt window.

The following command generates a key pair in the file attivio.key:

openssl genrsa -des3 -out attivio.key

You may also wish to use the -rand file argument to provide an arbitrary file to help seed the random number generator.

The following command generates a certificate for the key into the file attivio.crt:

openssl req -new -x509 -key attivio.key -out attivio.crt

This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt.  By default, the certificate authorizes one domain only (e.g., my.company.com), but you can configure a wildcard certificate (e.g., *.company.com) to authorize multiple subdomains of the primary domain.

For example:

openssl genrsa -des3 -out attivio.key
Generating RSA private key, 512 bit long modulus
...........................++++++++++++
..++++++++++++
e is 65537 (0x10001)
Enter pass phrase for attivio.key:
Verifying - Enter pass phrase for attivio.key:

# openssl req -new -x509 -key attivio.key -out attivio.crt
Enter pass phrase for attivio.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) [AU]:.
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:.
Organization Name (eg, company) [Internet Widgets Pty Ltd]:My Company
Organizational Unit Name (eg, section) []:My Organization
Common Name (eg, YOUR name) []:my.company.com
Email Address []:

#

 

Step 1c: Generating a SAN Certificate

In cases where a wildcard certificate cannot be applied to all project servers, you can create a single Subject Alternative Name (SAN) certificate to authorize them all. This most commonly occurs when using servers with different sub-domain depths, such as example.com and www.example.com, or servers in in different domains, like www.example.com and www.anotherexample.com. To do this, you will need the OpenSSL command-line tools. See Step 1b, above.

Create the SAN Certificate

Main Reference: Multiple Names on One Certificate

To create a SAN certificate, you must first create a custom openssl configuration file, which we name qa.conf. You may use your own file name.

The [req] section is the section that tells openssl what to do with certificate signing requests (CSRs). Within that section should be a line that sets req_extensions = v3_req, which enables Subject Alternative Name behavior. 

qa.conf
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
[req_distinguished_name]
countryName = Country Name (2 letter code)
countryName_default = US
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = MN
localityName = Locality Name (eg, city)
localityName_default = Minneapolis
organizationalUnitName    = Organizational Unit Name (eg, section)
organizationalUnitName_default    = Domain Control Validated
commonName = Internet Widgits Ltd
commonName_max    = 64
[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1   = www.foo.com
DNS.2   = www.bar.org
IP.1    = 192.168.1.1
IP.2    = 192.168.69.144

Modify the [alt_names] section at the bottom to include the list of domains (or IP addresses) to be trusted.


Generate the private key. Note that this step references your custom openssl configuration file.

openssl genrsa -out qa.key 2048

Create the certificate signing request file. Note that this step references your custom openssl configuration file.

openssl req -new -out qa.csr -key qa.key -config qa.conf

You will be prompted for many items of information, similar to the dialog shown in Step 1a.

To self-sign the certificate, follow this example:

openssl x509 -req -days 3650 -in qa.csr -signkey qa.key -out qa.crt -extensions v3_req -extfile qa.conf

You now have a valid SAN Certificate

Create a keystore using the certificate and the key

Attivio Platform can't use the .crt certificate file directly. The certificate and its key must be included in a Java Keystore (JKS) file. See Step 3b for instructions. 

You now have the keystore that uses your SAN certificate. it's now time to implement this into the Attivio project configuration.

Step 1d: Keys and Certificates from Other Sources

If you have keys and certificates from other sources, then you can proceed directly to Step 3.

You now have the minimal requirements to run an SSL connection and could proceed directly to Step 3 to load these keys and certificates into a JSSE keystore. However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect. This is often sufficient for testing, but most public site will need to Step 2b to obtain a certificate trusted by most popular clients.

Step 2: Request a Trusted Certificate

The keys and certificates generated in step 1 are sufficient to run an SSL connector. However the certificate you have generated will not be trusted by the user's browser and the user will be prompted to this effect.

To obtain a certificate that will be trusted by most common browsers, you need to request a well-known certificate authority (CA) to sign your key/certificate. Such trusted CAs include AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, and beTRUSTed, among others.

Each CA will have their own instructions which should be followed (look for JSSE or openssl sections), but all will involve a step to generate a certificate signing request file (CSR).

Step 2a: CSR from keytool

The following command generates the file attivio.csr using keytool for a key/cert already in the keystore:

<INSTALL_DIR>/jre/bin/keytool -certreq -alias admin -keystore conf/attivio.ks -file attivio.csr

For example:

/opt/attivio/platform/jre/bin/keytool -certreq -alias admin -keystore conf/attivio.ks -file attivio.csr
Enter keystore password: password

Step 2b: CSR from openssl

The following command generates the certificate signing request file attivio.csr using openssl for a key in the file attivio.key:

openssl req -new -key attivio.key -out attivio.csr

This command only uses the existing key from the attivio.key file and not a certificate in attivio.crt generated by step 1b, above. The details for the certificate need to be entered again.

Step 2c: Trusting your Self-Signed Certificate

Note that if you use an internal custom CA that is not one of the common ones included by default in the JVM cacerts file, you will need to manually add your CA to the cacerts keystore used by the Attivio JRE. For example,

sudo <INSTALL_DIR>/jre/bin/keytool -import -trustcacerts -file MyCompanyCA.crt -alias CompanyCA -keystore <INSTALL_DIR>/jre/lib/security/cacerts

You'll be asked for a keystore password. To save you a trip to Google, the default password for the cacerts keystore is changeit. As implied, you probably should change it.

If you use an internal custom CA that is not included in the cacerts keystore and neglect this step, you may see errors like this in your Attivio logs:

javax.net.ssl.SSLHandshakeException: 
sun.security.validator.ValidatorException: PKIX path building failed: 
sun.security.provider.certpath.SunCertPathBuilderException: unable to 
find valid certification path to requested target

 

Step 3: Loading the Keystore

A certificate will need to be loaded into a a JSSE keystore before Attivio can use it. The procedure for using keytool (Step 1A) did this already, but other approaches will require manually loading the certificate into the keystore.

Combined Private Key and Certificate

You need both the private key and the certificate in the keystore. So the certificate should be loaded into the keystore used to generate the CSR (step 2a). If your key pair is not in a keystore (for example, if generated as step 1b), then you will need to use the PKCS12 format to load both key and certificate as in step 3b.

Step 3a: Loading PEM Certificates with keytool

A certificate in PEM form may be directly loaded into a keystore with keytool. The PEM format is a text encoding of certificates and is produced by openssl (as in step 1b) and is returned by some CAs. An example PEM file is:

attivio.crt
-----BEGIN CERTIFICATE-----
MIICSDCCAfKgAwIBAgIBADANBgkqhkiG9w0BAQQFADBUMSYwJAYDVQQKEx1Nb3J0
IEJheSBDb25zdWx0aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNV
BAMTEWpldHR5Lm1vcnRiYXkub3JnMB4XDTAzMDQwNjEzMTk1MFoXDTAzMDUwNjEz
MTk1MFowVDEmMCQGA1UEChMdTW9ydCBCYXkgQ29uc3VsdGluZyBQdHkuIEx0ZC4x
DjAMBgNVBAsTBUpldHR5MRowGAYDVQQDExFqZXR0eS5tb3J0YmF5Lm9yZzBcMA0G
CSqGSIb3DQEBAQUAA0sAMEgCQQC5V4oZeVdhdhHqa9L2/ZnKySPWUqqy81riNfAJ
7uALW0kEv/LtlG34dOOcVVt/PK8/bU4dlolnJx1SpiMZbKsFAgMBAAGjga4wgasw
HQYDVR0OBBYEFFV1gbB1XRvUx1UofmifQJS/MCYwMHwGA1UdIwR1MHOAFFV1gbB1
XRvUx1UofmifQJS/MCYwoVikVjBUMSYwJAYDVQQKEx1Nb3J0IEJheSBDb25zdWx0
aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNVBAMTEWpldHR5Lm1v
cnRiYXkub3JnggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADQQA6NkaV
OtXzP4ayzBcgK/qSCmF44jdcARmrXhiXUcXzjxsLjSJeYPJojhUdC2LQKy+p4ki8
Rcz6oCRvCGCe5kDB
-----END CERTIFICATE-----

The following command will load a PEM-encoded certificate in the attivio.crt file into a JSSE keystore:

<INSTALL_DIR>/jre/bin/keytool -keystore conf/attivio.ks -import -alias admin -file attivio.crt -trustcacerts

Depending on the situation you may not require the -trustcacerts option. Try the operation without it if you like.

If the certificate your receive from the CA is not in a format that keytool understands, then the openssl command can be used to convert
formats:

openssl x509 -in attivio.der -inform DER -outform PEM -out attivio.crt

Step 3b: Loading PKCS12 keys and certificates using keytool

If you have a key and certificate in separate files, they need to be combined into a PKCS12 format file to be loaded into a new keystore. The certificate can be one you generated yourself or one that has been returned from a CA in response to your CSR.

 

The following openssl command will combine the keys in attivio.key and the certificate in the attivio.crt file into the attivio.pkcs12 file:

openssl pkcs12 -inkey attivio.key -in attivio.crt -export -out attivio.pkcs12

If you have a chain of certificates, because your CA is an intermediary, build the pkcs12 file like this:

# cat example.crt intermediate.crt [intermediate2.crt]... rootCA.crt > cert-chain.txt
# openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12

The order of certificates must be from server to rootCA, as per RFC2246 section 7.4.2.

OpenSSL is going to ask you for an "export password". A non-empty password seems to be required to make the next step work. The
resulting PKCS12 file may be loaded into a JSSE keystore with the following command:

<INSTALL_DIR>/jre/bin/keytool -importkeystore -srckeystore attivio.pkcs12 -srcstoretype PKCS12 -destkeystore conf/attivio.ks

This asks for two passphrases. Give the password from the last step as the input passphrase and you are set. The "output passphrase" will need to appear in your jetty.xml config file as both the Password and KeyPassword of the SunJsseListener that will use the certificate.

Step 4: Configure a JsseListener

Edit <install-dir>\conf\jetty.xml and follow the directions in the comments, which ask you to comment or uncomment certain blocks of code to enable SSL support. See Enabling SSL HTTPS for AIE Web Applications.

You will need to adjust the password, keyPassword and trustPassword configuration options to match the passwords you used to generate the keystore above.

This configuration change disables non-encrypted http support so all access to the admin interface will need to be via https

 

Passwords

If jetty is given a password that begins with "OBF:" it is treated as an obfuscated password. Passwords can be obfuscated by running aie-exec password.  This can protect passwords from casual observation.

On Windows:

> bin\aie-exec.exe password -p <your password>

<your password>
OBF:1xfd1zt11uha1ugg1zsp1xfp
MD5:a029d0df84eb5549c641e04a9ef389e5

On Linux:

$ ./bin/aie-exec password -p <your password>

<your password>
OBF:1xfd1zt11uha1ugg1zsp1xfp
MD5:a029d0df84eb5549c641e04a9ef389e5

If you do not specify -p you will be prompted for your password

 

Testing Self-Signed Certificates

This is an optional procedure for people who are using self-signed certificates. We will tell chrome to trust this certificate, and view the results

  1. Import the certificate you created in Step 1 into Chrome
  2. Go to Settings > Advanced > HTTPS/SSL > Manage Certificates
  3. Click "import", and import your certificate
  4. Restart Chrome
  5. Go to the Administration UI's of your AIE nodes and observe that you have access to the nodes listed in the SAN certificate, but not to other nodes.

 

  • No labels