Edge Encryption Support

Feature enhancement available in Helium 6.0.2 release

The DataSync Agent can be configured to decrypt ServiceNow records with data encrypted using Edge Encryption. Perspectium provides support for records encrypted using the AES-128 and AES-256 options.

Prerequisites

First, you will need to set up one of the Perspectium DataSync Agents.

You should stop running your DataSync Agent before making any Agent configuration changes.

The DataSync Agent provides a plugin to support decrypting data that is edge encrypted. In order to decrypt this, you will need the following:

Edge Encryption enabled in your ServiceNow instance
Edge Encryption proxy server installed and configured
Keystore containing the encryption key used for Edge Encryption. This keystore can be stored in an Azure Key Vault cloud key management or stored locally on a filesystem the Agent as access to.

With this information available, add the following configuration directives to your task definition within your agent.xml file:

All attributes are required to access the keystore from the Azure Key Vault.

For Azure Key Vault, add the following:

Directive

Parameters

Required?

Example Value

Plugin that will decrypt Edge Encrypted replicated data.

Parameter	Description
keystore	Specifies where the keystore is located. You can choose between azure or azure_api as the value.
vault_tenant	tenant_id for the Azure Key Vault containing the keystore*
vault_url	URL to the Azure Key Vault*
vault_principal	principal_id for the Azure Key Vault*
principal_secret	password for the Azure Key Vault*
secret_name	Name of the keystore^
keystore_password	password for the keystore^
keystore_alias	Name of the key alias^
alias_password	Password for the key^
The following parameters are used for keystore="azure_api":
app_name	Name of the application making the requests to the API
api_url	API endpoint
key_vault_type	Where the Azure Key Vault is stored

*See Authentication in Azure Key Vault for more information on these configurations.

^See Edge Encryption properties for more information on these configurations.

NOTE: The Azure KeyVault uses its own HTTP client, which means Azure is making network connections separate from Perspectium messages and instance connections. Thus, to access Azure KeyVault through a proxy, add the following:

Parameter	Description
proxy	The URL of the proxy server to connect to. proxy="http://example.com/"
proxy_port	Port number this client will use proxy_port=”8080”
proxy_user	The username to authenticate with the proxy server proxy_user=“proxyConfiguredUser”
proxy_password	The password to authenticate with the proxy server proxy_password=“proxyConfiguredUserPassword”

Click here to see azure keystore example...

<config>
	<agent>
		<subscribe>
			<task> 
				...
				<plugin keystore="azure"
					proxy="http://example.com"
					proxy_port="8080"
                 	vault_tenant="VAULT_TENANT_GOES_HERE" 
                 	vault_url="VAULT_URL_GOES_HERE"
                 	vault_principal="VAULT_PRINCIPAL_GOES_HERE" 
                 	principal_secret="PRINCIPAL_SECRET_GOES_HERE" 
                 	secret_name="SECRET_NAME_GOES_HERE"
                 	keystore_password="KEYSTORE_PASSWORD_GOES_HERE" 
                 	keystore_alias="KEYSTORE_ALIAS_GOES_HERE" 
  				 	alias_password="ALIAS_PASSWORD_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
			</task>
		</subscribe>
	</agent>
</config>

Click here to see azure_api keystore example...

<config>
	<agent>
		<subscribe>
			<task> 
				...
				<plugin keystore="azure_api"
					proxy="http://example.com"
					proxy_port="8080"
                 	vault_tenant="VAULT_TENANT_GOES_HERE" 
                 	vault_url="VAULT_URL_GOES_HERE"
                 	vault_principal="VAULT_PRINCIPAL_GOES_HERE" 
                 	principal_secret="PRINCIPAL_SECRET_GOES_HERE" 
                 	secret_name="SECRET_NAME_GOES_HERE"
                 	keystore_password="KEYSTORE_PASSWORD_GOES_HERE" 
                 	keystore_alias="KEYSTORE_ALIAS_GOES_HERE" 
  				 	alias_password="ALIAS_PASSWORD_GOES_HERE"
					app_name=""
					api_url="URL_GOES_HERE"
					key_fault_type="0">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
			</task>
		</subscribe>
	</agent>
</config>

Yes

See example below.

Example of a complete agent.xml configuration with the keystore in an Azure Key Vault

<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
    <agent>
        <max_reads_per_connect>1</max_reads_per_connect>
        <polling_interval>5</polling_interval>
        <test_mode/>
        <subscribe>
            <task>
                <polling_interval>5</polling_interval>
                <task_name>oracle_subscriber_automated_test</task_name>
                <handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
                <decryption_key>some_decryption_key_here</decryption_key>
                <message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
                <use_cache/>
                <instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
                <database_type>sqlserver</database_type>
                <database_port>1234</database_port>
                <database_server>SERVER_URL</database_server>
                <database_user>USER</database_user>
                <database_password>PASSWORD</database_password>
                <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
                <database>DATABASE_NAME</database>
                <skip_columns_log_interval>200</skip_columns_log_interval>
				<plugins>
					<plugin keystore="azure"
                            vault_tenant="12345678-ab12-ab12-ab12-123456789ab"
                            vault_url="https://url.vault.azure.net/"
                            vault_principal="12345678-ab12-ab12-ab12-123456789ab"
                            principal_secret="3213156165-adasdasd_a1s5d6a5s1d6a"
                            secret_name="some_secret_name"
							keystore_password="efg123"
                            keystore_alias="128bitkey"
                            alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin
					</plugin>
				</plugins>
        </task>
    </subscribe>
</agent>
</config>

If the keystore containing the encryption key is saved locally in the filesystem that the Agent has access to, add the following:

Directive

Description

Required?

Example Value

Plugin that will decrypt Edge Encrypted replicated data.

Parameter	Description
keystore	Specifies where the keystore is located. Value: local
keystore_path	File path to the keystore^
keystore_password	Password for the keystore^
keystore_alias	Name of the key alias^
alias_password	Password for the key^

^See Edge Encryption properties for more information on these configurations.

<config>
	<agent>
		<subscribe>
			<task> 
				...
				<plugin keystore="local"
                keystore_path="KEYSTORE_PATH_GOES_HERE"
                keystore_password="KEYSTORE_PASSWORD_GOES_HERE" 
                keystore_alias="KEYSTORE_ALIAS_GOES_HERE"
 				alias_password="ALIAS_PASSWORD_GOES_HERE">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
			</task>
		</subscribe>
	</agent>
</config>

Yes

See example below.

Example of a complete agent.xml configuration with the keystore in a local filesystem the Agent has access to:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<config>
    <agent>
        <max_reads_per_connect>1</max_reads_per_connect>
        <polling_interval>5</polling_interval>
        <test_mode/>
        <subscribe>
            <task>
                <polling_interval>5</polling_interval>
                <task_name>oracle_subscriber_automated_test</task_name>
                <handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
                <decryption_key>some_decryption_key_here</decryption_key>
                <message_connection user="USER" password="PASSWORD" queue="psp.out.replicator.dev1234">https://URL.perspectium.net</message_connection>
                <use_cache/>
                <instance_connection user="USER" password="PASSWORD">https://dev1234.service-now.com</instance_connection>
                <database_type>sqlserver</database_type>
                <database_port>1234</database_port>
                <database_server>SERVER_URL</database_server>
                <database_user>USER</database_user>
                <database_password>PASSWORD</database_password>
                <database_parms>lockTimeout=15000;queryTimeout=15</database_parms>
                <database>DATABASE_NAME</database>
                <skip_columns_log_interval>200</skip_columns_log_interval>
				<plugins>
					<plugin keystore="local"
                		keystore_path="abcdefg"
               			keystore_password="efg123"
                        keystore_alias="128bitkey"
 						alias_password="abc123">com.perspectium.replicator.sql.plugin.SQLSubscriberDecryptColumnPlugin</plugin>
        </task>
    </subscribe>
</agent>
</config>

If you want to use attachment handling with edge encryption so the attachments are each saved as a complete file, see Merging Attachments in the Database.

Content

Space Tools

Feature enhancement available in Helium 6.0.2 release

Prerequisites

Can't find what you're looking for?

See the FAQ or browse the Perspectium Community Forum.