Edge Encryption proxy Server installation

[jonnyseymour]

If you are lucky enough to get hold of our ServiceNow reverse proxy that also encrypts, you would find this blog useful. While visiting ServiceNow San Diego office, I managed to get my hands on a system to set up ServiceNow Edge encryption reverse proxy. A reverse proxy is a type of proxy server that retrieves resources on behalf of a client. These resources are then returned to the client as if they originated from the proxy server itself. You can set your OWN domain name even when the service is coming from the ServiceNow cloud. This is one of the most requested feature since ever. e.g. You can set the server as "drstrangefan.domain.com" if you own the domain, then users would login with https: // drstrangefan.domain.com to your instance. Awesome! Now, we also added a superb "transparent" encryption (I need to say, the main feature). As our reverse proxy sits on YOUR network, the data could be transparently encrypted with little action from your customers and virtually NEVER leaves your proxy location (comply with some geographical restrictions).   Sounds simple, huh?

I will use this example of how I set up my edge encryption reverse proxy on Linux to work. There are many other ways. I would try to simplify this complex use case.

How to install Edge Encryption reverse proxy on Linux

1. Pre-requisites: Linux/Windows server and a MySQL.
2. Enable the Edge Encryption plugin.
3. Download the installer into Linux/Windows system.
   • DO NOT uncompress/unzip.
4. Set up with keystore supplied.
   • DO backup original file.
   • RETAIN the ServiceNow signature.
5. Set up the reverse proxy.
6. DO backup original configuration.
   • DO NOT start proxy yet.
7. Set up your instance default key. You need to start the proxy.
   • DO NOT update OOTB rules or configurations yet.
8. Shutdown and start the reverse proxy.
9. Run a test by logging by the reverse proxy URL using your browser.

There are a lot of "DO NOT" actions. They are here because security is the top priority on Edge reverse proxy. Our proxy will detect "unsigned" changes that could LOCK your configurations. Edge encryption proxy trust is limited.

1. Pre-requisites: Linux/Windows server and a My-SQL.

The first thing you will need to get started with Edge Encryption reverse proxy, is a Linux/windows server.

All proxies connected to the same instance need to use the same MYSQL database.

Ensure you have all the libraries required to connect to mysql. Then set up your Linux/Windows server to connect to the mysql server.

Once that is complete, you have the basic components necessary to start the Edge Encryption proxy.

I was glad have MySQL installed on my behalf so I could not share details on this experience. Please feel free to add comments   with your experiences.

2. Enable the Edge Encryption plugin

To enable the "Edge Encryption" plugin, you will need to contact your ServiceNow account manager. I am afraid you need to be entitled for this plugin being enabled. Your ServiceNow account manager will activate the plugin for you on your instance.

3. Download the proxy installer into Linux/Windows system. Do NOT uncompress/unzip

Once you have Edge Encryption enabled on your instance, get the edge encryption installer. You will need to login as admin and elevate your privileges to see the download page for Edge Encryption.

Here is how you can elevate your role to security_admin:

Once you have the right privileges, select security_admin, then click ok.

How to download Edge Encryption proxy:

1. In the application navigator, type in Edge Encryption Configuration
2. Select Installation & Download
3. Click on Downloads

Now breath, The next are the installation steps:

I retrieved the link from the download page. In my case, I would download linux 64 bit installer:

> wget <link retrieved from the download page>

----

Then, I validate the installation instructions

TYPE

> java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip

RETURNS

>

>>>> [ec2-user@ip-10-0-0-210 edge]$ java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip

>>>> option: [--mode] MODE required

>>>>

>>>> --help

>>>>

>>>>       -m|--mode                                                     MODE                                     [required, modes: install, upgrade]

>>>>

>>>>       -s|--dst-dir                                               DESTINATION DIRECTORY   [optional for mode: install: default: $(PROXY_NAME)_$(PORT)]

>>>>       -d|--proxy-dir                                           PROXY DIRECTORY               [required for mode: upgrade]

>>>>       -n|--proxy-name                                         PROXY NAME                         [required for mode: install]

>>>>       -h|--host                                                     INSTANCE HOST                   [required for mode: install]

>>>>       -p|--port                                                     INSTANCE PORT                   [required for mode: install]

>>>>       -proto|--protocol                                     INSTANCE PROTOCOL           [required for mode: install]

>>>>

>>>> Examples:

>>>>

>>>> 1) Install EdgeEncryption proxy into directory test_16001:

>>>>

>>>>       java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip -m install -n test -h 1.2.3.4 -p 16001 -proto http

>>>>

>>>> 2) Install EdgeEncryption proxy into SecureProxy directory, and configure to use secure HTTPS connection:

>>>>

>>>>       java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip -m install -n test -s SecureProxy -h 1.2.3.4 -p 443 -proto https

>>>>

>>>> 3) Upgrade EdgeEncryption proxy installed in directory test_16001:

>>>>

>>>>       java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip -m upgrade -d test_16001

I have chosen the second

>>>> 2) Install EdgeEncryption proxy into SecureProxy directory, and configure to use secure HTTPS connection:

Install EdgeEncryption proxy into SecureProxy directory by using the example command line on the output and

REPLACE   1.2.3.4 with the instance name e.g. xxxxxx.service-now.com.

The parameters information when un-compressing the zip file would be used on the edgeencryption.properties created by the installer.

Here is me, creating the installation directory

TYPE the

> java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip -m install -n test -s SecureProxy -h edgeproxytraining2.service-now.com -p 443 -proto https

It returns:

>>>>> [ec2-user@ip-10-0-0-210 edge]$ java -jar edgeencryption-dist-2.1.1-linux-x86-64.zip -m install -n test -s SecureProxy -h xxxxxx.service-now.com -p 443 -proto https

>>>>> Sep 28, 2016 1:46:56 PM com.snc.cloudedge_zip.CommandProcessor buildCommand

>>>>> INFO: option: dist-file: file:/home/ec2-user/edge/edgeencryption-dist-2.1.1-linux-x86-64.zip

>>>>> Sep 28, 2016 1:46:56 PM com.snc.cloudedge_zip.CommandProcessor buildCommand

>>>>> INFO: option: dst-dir: /home/ec2-user/edge/SecureProxy

>>>>> Sep 28, 2016 1:46:56 PM com.snc.cloudedge_zip.CommandProcessor buildCommand

>>>>> INFO: option: proxy-name: test

>>>>> Sep 28, 2016 1:46:56 PM com.snc.cloudedge_zip.CommandProcessor buildCommand

>>>>> INFO: option: port: 443

>>>>> Sep 28, 2016 1:46:56 PM com.snc.cloudedge_zip.CommandProcessor buildCommand

>>>>> INFO: option: protocol: https

>>>>> Sep 28, 2016 1:46:56 PM com.snc.cloudedge_zip.CommandProcessor buildCommand

>>>>> INFO: option: extra-properties: 0

>>>>> Sep 28, 2016 1:46:56 PM com.snc.dist.upgrade.common.extract.ZipExtractor extract

>>>>> INFO: extracting: file:/home/ec2-user/edge/edgeencryption-dist-2.1.1-linux-x86-64.zip => /home/ec2-user/edge/SecureProxy

>>>>> Sep 28, 2016 1:46:57 PM com.snc.cloudedge_zip.CloudedgePermissions execute

>>>>> INFO: setting permissions: /home/ec2-user/edge/SecureProxy

>>>>> Sep 28, 2016 1:46:58 PM com.snc.dist.upgrade.common.extract.ZipExtractor extract

>>>>> INFO: extracting: file:/home/ec2-user/edge/SecureProxy/java/mid-jre-1.8.0_40-4-linux-x86-64.zip => /home/ec2-user/edge/SecureProxy/java

Now, you can relax once again.

4. Set up with keystore supplied.

Set up the installation with the java keystore supplied. My advice for this step of the process is to backup the original file and retain the ServiceNow signature.

If you have an intermediate reverse proxy, ensure to add the public certificate to the keystore as well. However, if the SSL handshake fails, add it to the <java>/lib/security/cacerts (keystore). You'll be prompted for the store password. The default password is changeit.

Setting up with the supplied keystore is prone to errors. Keep these tips in mind:

• DO NOT create an empty keystore. The provided keystore contains an alias "servicenow" which is required. The original password is "changeme".
• There are four(4) certificates to function:
  • Edge signature (rsa)
  • Edge Web certificate (rsa)
  • Edge encryption (aes)
  • The alias "servicenow" on the provided keystore
• For any additional network element (e.g. proxy, servers, load-balancers) in-between the reverse proxy and the instance, their public certificates (and chains) need to be added to the keystore.
• Each keystore password needs to match the password of the aliases passwords inside. Both passwords need to be the same.
• Make sure that the new names of keystore aliases are created in LOWER CASE because in Edge encryption this field is case-sensitive. e.g. if you have a keystore alias "TestEdge", use "testedge" when creating the alias and the edge encryption properties to avoid mismatches.
• Once again (3rd time check), validate the "servicenow" alias is on the keystore. It is required because the original rules are signed with this certificate. If you keystore has a different password, change this alias password to match. (See stage 2 below)
• Validate the keystore password once again (specially after importing other keystores).

Keystore with same password	TRUE	FALSE
Edge Signature (RSA)	OK	Fails
Edge Web Certificate(RSA)	OK	Fails
Edge Encryption(EAS)	OK	Fails
Servicenow Signature(RSA)	OK	Fails

The provided keystore contains an alias "servicenow" which is required because the original rules are signed with this certificate.

Stage 1: Generate the certificates

For my testing, I would use "changeme" for the password on the keystore and aliases by executing the following commands.

First, navigate to the SecureProxy folder, then go to the keystore folder.

> ../java/jre/bin/keytool -genkey -alias jscert -keyalg rsa -keystore keystore.jceks -storetype jceks

> ../java/jre/bin/keytool -genkey -alias jssign -keyalg rsa -keystore keystore.jceks -storetype jceks

> ../java/jre/bin/keytool -genseckey -alias jsaes128 -keyalg aes -keystore keystore.jceks -storetype jceks -keysize 128

Note there are 3 important keys to generate: RSA (certificate), RSA (to sign) and AES (to encrypt). Note the third is AES

Here is the output of the previous command:

Generating the certificate for the Web server holding the proxy. This is the one you want sign with a CA authority.

> ../java/jre/bin/keytool -genkey -alias jscert -keyalg rsa -keystore keystore.jceks -storetype jceks

>>>> [ec2-user@ip-10-0-0-210 keystore]$ ../java/jre/bin/keytool -genkey -alias jscert -keyalg rsa -keystore keystore.jceks -storetype jceks

>>>> Enter keystore password:     changeme

>>>> What is your first and last name?

>>>>     [Unknown]:   JS

>>>> What is the name of your organizational unit?

>>>>     [Unknown]:   Hero

>>>> What is the name of your organization?

>>>>     [Unknown]:   Associations

>>>> What is the name of your City or Locality?

>>>>     [Unknown]:   San Diego

>>>> What is the name of your State or Province?

>>>>     [Unknown]:   Far far away

>>>> What is the two-letter country code for this unit?

>>>>     [Unknown]:   FA

>>>> Is CN="JS ", OU=Hero, O=Associations, L=San Diego, ST=Far far away, C=FA correct?

>>>>     [no]:   yes

>>>>

>>>> Enter key password for <jscert>

>>>>         (RETURN if same as keystore password):   changeme

>>>> Re-enter new password: changeme

>>>>

This is another certificate, internal to edge: the signature.

>../java/jre/bin/keytool -genkey -alias jssign -keyalg rsa -keystore keystore.jceks -storetype jceks

>>>>> [ec2-user@ip-10-0-0-210 keystore]$ ../java/jre/bin/keytool -genkey -alias jssign -keyalg rsa -keystore keystore.jceks -storetype jceks

>>>>> Enter keystore password: changeme

>>>>> What is your first and last name?

>>>>>     [Unknown]:   JS

>>>>> What is the name of your organizational unit?

>>>>>     [Unknown]:   Hero

>>>>> What is the name of your organization?

>>>>>     [Unknown]:   Associations

>>>>> What is the name of your City or Locality?

>>>>>     [Unknown]:   San Diego

>>>>> What is the name of your State or Province?

>>>>>     [Unknown]:   Far Far away

>>>>> What is the two-letter country code for this unit?

>>>>>     [Unknown]:   FA

>>>>> Is CN=JS, OU=Hero, O=Associations, L=San Diego, ST=Far Far away, C=FA correct?

>>>>>     [no]:   yes

>>>>>

>>>>> Enter key password for <jssign>

>>>>>         (RETURN if same as keystore password):   changeme

>>>>> Re-enter new password: changeme

Finally, then we need to generate the encryption certificate on AES format so Edge can encrypt.

>../java/jre/bin/keytool -genseckey -alias jsaes128 -keyalg aes -keystore keystore.jceks -storetype jceks -keysize 128

>>> [ec2-user@ip-10-0-0-210 keystore]$ ../java/jre/bin/keytool -genseckey -alias jsaes128 -keyalg aes -keystore keystore.jceks -storetype jceks -keysize 128

>>> Enter keystore password: changeme

>>> Enter key password for <jsaes128>

>>>         (RETURN if same as keystore password):   changeme

>>> Re-enter new password: changeme

Stage 2: Keystore validation

Recheck the keystore password matches the certificates.

If you import certificates from another keystore, or to validate the correct password was USED on all keystores, then reset it again as follow:

To validate keystore password, reset it to the same password as follow (on this case "changeme" to "changeme"):

>../java/jre/bin/keytool -storepasswd -keystore keystore.jceks -storepass changeme -storetype jceks -keypass changeme -new changeme

If there is AN ERROR it would show: keytool error: java.io.IOException: Keystore was tampered with, or password was incorrect

To validate aliases password, reset it to the same password as follow (on this case "changeme" to "changeme"):

>../java/jre/bin/keytool -keypasswd -alias jscert -keystore keystore.jceks -storepass changeme -storetype jceks -keypass changeme -new changeme

>../java/jre/bin/keytool -keypasswd -alias jsaes128 -keystore keystore.jceks -storepass changeme -storetype jceks -keypass changeme -new changeme

>../java/jre/bin/keytool -keypasswd -alias jssign -keystore keystore.jceks -storepass changeme -storetype jceks -keypass changeme -new changeme

If there is AN ERROR it would show: keytool error: java.security.UnrecoverableKeyException: Given final block not properly padded

Stage 3: Validate the "servicenow" alias is part of the keystore aliases

> ../java/jre/bin/keytool -list -v -keystore keystore.jceks -storepass changeme -storetype jceks -alias servicenow

It should show:

>>>> Alias name: servicenow

>>>> Creation date: 13-Jul-2015

>>>> Entry type: trustedCertEntry

>>>>

>>>> Owner: CN=Unknown, OU=Platform Development, O=ServiceNow Inc., L=San Diego, ST=CA, C=US

>>>> Issuer: CN=Unknown, OU=Platform Development, O=ServiceNow Inc., L=San Diego, ST=CA, C=US

>>>> Serial number: b6b15d5

>>>> Valid from: Mon Jul 13 17:54:15 PDT 2015 until: Sun Oct 11 17:54:15 PDT 2015

>>>> Certificate fingerprints:

>>>>           MD5:   90:CD:AC:1D:FB:DC:32:98:51:26:69:4C:56:1E:1C:40

>>>>           SHA1: 6B:46:C7:A6:67:6D:8E:BC:22:08:B6:47:F8:3E:3D:A7:91:30:AE:C7

>>>>           SHA256: 95:50:4C:25:C6:01:D1:DC:5B:19:2E:54:64:9C:1A:02:22:23:68:AC:33:87:D7:D0:04:48:FD:BD:00:8F:65:D1

>>>>           Signature algorithm name: SHA256withRSA

>>>>           Version: 3

 

5. Set up the reverse proxy configuration properties.

DO backup original configuration by export to XML files.

DO NOT start proxy.

On a notepad like editor, open the edgeencryption.properties file:

Here is the example of my properties

******** edgeencryption.properties **********

## edgeencryption.target.username is the user with "edgeencryption" role

## edgeencryption.target.password is the user password

edgeencryption.target.username = awesomeuser

edgeencryption.target.password = awesomeuser1

...

edgeencryption.target.port = 443

...

edgeencryption.proxy.host = 54.69.186.134

edgeencryption.proxy.name = JSProxy Server HEXELL

...

edgeencryption.proxy.https.keystore.path = keystore/keystore.jceks

### edgeencryption.proxy.https.keystore.password = <ChangeMe>

### edgeencryption.proxy.https.cert.alias = <ChangeMe>

edgeencryption.proxy.https.keystore.password = changeme

edgeencryption.proxy.https.cert.alias = jscert

....

edgeencryption.db.user = root

edgeencryption.db.password =

....

edgeencryption.proxy.signature.keystore.path = keystore/keystore.jceks

edgeencryption.proxy.signature.keystore.password = changeme

edgeencryption.proxy.signature.keystore.keyalias = jssign

...

### edgeencryption.encrypter.properties.password = <ChangeMe>

edgeencryption.keystore.path = keystore/keystore.jceks

edgeencryption.keystore.password = changeme

******** edgeencryption.properties **********

6. Set up your instance default key. You need to start the proxy. DO NOT update out of the box (OOTB) rules or existing configurations.

This is just to set the default keys. As we are setting the default certificate, Do not change edge rules because the proxy will LOCK them. Edge proxy depends on the certificates to validate rules in the instance. Our original rules depends on the "servicenow" certificate, whilst any any would depend on the created Edge certificates.

To setup a default key, as documented:

1. Navigate to Set Up Keys
2. On the instance, set the details key for the instance.

For example, on instance:

On Set Up Keys: (/sys_encryption_key_configuration.do?sys_id=e593a6590a0a3c18004a49d0106b5cbd)

Then set to > jsaes128, 128 bits, keystore.

Please note this is CASE sensitive. Please use ALL aliases in lowercase.

1. Click Next and then Next, again.
2. Change Default Keys to the one created. e.g. Default Key 128 bits = jsaes128, Default 256 = (empty)

7. Shutdown and start the reverse proxy

Then go to SecureProxy and type:

>./shutdown; ./startup.sh

Ensuring correct permissions: ec2-user:ec2-user

Cleaning local tmp: /home/ec2-user/edge/SecureProxy/tmp

--- Bundled JRE test ---

java version "1.8.0_40"

Java(TM) SE Runtime Environment (build 1.8.0_40-b26)

Java HotSpot(TM) 64-Bit Server VM (build 25.40-b25, mixed mode)

------- end test -------

Starting Edge Encryption (SecureProxy)...

To validate it is working correctly, review the logs

>tail logs/edgeencryption.log

>>>> 2016-09-28 14:25:35,673 INFO   Edge Encryption proxy home directory: ..

>>>> 2016-09-28 14:25:35,684 INFO   Reading properties from: /home/ec2-user/edge/SecureProxy/bin/../conf/edgeencryption.properties

>>>> 2016-09-28 14:25:36,538 INFO   Starting Edge Encryption proxy

>>>> 2016-09-28 14:25:37,956 INFO   Connected to database: jdbc:mysql://localhost as user root

>>>> 2016-09-28 14:25:37,970 INFO   Bootstrapping database edgeencryption

>>>> 2016-09-28 14:25:38,136 INFO   Done bootstrapping database edgeencryption

8. Run a test by logging by the reverse proxy URL using your browser

If the proxy starts correctly and detects the default key, try login by the proxy using the port specified on the edgeencryption.properties

NOTE: This is a reverse proxy. DO NOT SET ON the browser cache details. Just type the server and port the proxy is set up on.

Just go to the URL   https ://<proxy-server>:<port set>

e.g https://54.69.186.134:8082

Now you would be able to set up your edge encryption configuration, as the default key has been set and the proxy should start fine.

I have tested using Chrome, Helsinki, Linux CentOS release 6.6 (Final), and MySQL 14.14. Linux 2.6.32-504.8.1.el6.x86_64 and mysql   Ver 14.14 Distrib 5.6.22, for Linux (x86_64) using   EditLine wrapper.

Finally, setting a new edge encryption proxy is possible, once you have a my-sql server ready, download and install the proxy, then set your java keystore, then on the instance you register your key for edge, start your proxy, wait a few minutes, then set your default key and restart your proxy. I hope you can choose the best domain name for your reverse proxy. That is all?

More information can be found here:

• ServiceNow Edge Encryption
• Secure your data and perfect performance
• TechBytes Episode 28: Edge Encryption
• My other blogs
• Browser access to an instance via an Edge Proxy fails and results in a Secure Connection Failed mess...KB0621204)
• SAML SSO Login Fails When Attempted by the Edge Proxy URL   (KB0621210)
• Edge Encryption proxy fails to start with error "failed signature validation" (KB0621218)
• Edge Encryption proxy fails to start with error "Failed to load encryption rules" (KB0621286)
• How to increase debug logging for the Edge Encryption proxy(KB0621289)
• Attachments on tables with encrypted attachments are corrupt (KB0621559)
• How to implement Multiple Provider Single Sign-On including an Edge Encryption Proxy URL login (KB06...