Neuron ESB CertainSafe Connector

Introduction

Neuron ESB’s CertainSafe Adapter is the culmination of a partnership between the two companies. The adapter enhances your efforts to securely store and transmit encrypted secret data while leaving mundane information in clear text form. It does so by simplifying the steps you employ to interact with your CertainSafe Digital Vault from your Neuron ESB based integration infrastructure. Together Neuron ESB and CertainSafe enable automated data security for databases, files, processes, messages and API communications.

The Neuron ESB CertainSafe adapter functions in a Solicit/Response pattern in that the adapter listens for messages published to the bus based on its Topic. Those messages can contain data bound for secure storage and encryption by the CertainSafe service or tokens that map to previously secured data. The response from the CertainSafe Digital Vault service is a new token in the former case and the returned data in the latter.

Before reading this document

If you are not familiar with Neuron ESB Adapters, take a moment to consult our online help: https://www.peregrineconnect.com/documentation-kb/adapter-overview/. This document assumes you have the following knowledge:

1. What adapters are and how they are leveraged in Neuron ESB
2. Register a Neuron ESB Adapter within a Neuron ESB Solution
3. Create an Adapter Endpoint in a Neuron ESB Solution
4. Set a Neuron ESB Adapter Endpoint Properties
5. Invoke a Neuron ESB Adapter Endpoint

Conversely if you are not familiar with the CertainSafe Digital Vault service then take some time to read CertainSafe’s online help: https://certainsafe.com/. There you’ll learn how to leverage the service to:

1. Create and use your digital safety deposit box
2. Securely lock down client portals
3. Protect and secure all of the data in and around payment transactions
4. Use the Security as a Service SDK

If your organization isn’t already registered for the CertainSafe service, you can complete that process here: https://registration.certainsafe.com/register?ft=true. You’ll receive the ID’s necessary for configuring the Neuron ESB CertainSafe adapter and messages in a follow-up email from CertainSafe.

CertainSafe Adapter

The following steps assume the user has already setup a topic, subscriber, and publisher for the adapter to send and receive messages from.

The first step is to register the adapter in the “Connections” tab in Neuron Explorer.  Under the “Connection Methods” list, click on “Adapter Registration” and then click “New” in the main panel of Neuron ESB.  Select the CertainSafe adapter in the adapter drop-down menu (make sure “.NET” is chosen from the “Family” drop-down), give it an appropriate name, and then click “Apply”.

Next, in the “Endpoints” list, click on “Adapter Endpoints”.  Create a new adapter endpoint by clicking the “New” button, then select the registered adapter’s name from the “Adapter” drop-down menu.  Choose a subscriber from the “Party Id” menu and then click on the properties tab.  Enter the appropriate values (properties are described below), make sure the adapter is enabled in the “General” tab, and then click apply.

Adapter Properties

Use CertainSafe Test URL:  When set to true, CertainSafe’s testing URL will be used instead of the production URL.

• Base URL:  The URL the adapter will make its REST calls to.
• Authentication ID:  This is given by CertainSafe to users.  If this field is not present in the message body, the adapter will use the value provided here.
• Merchant Token:  This is given by CertainSafe to users.  If this field is not present in the message body, the adapter will use the value provided here.  The Sender and Merchant tokens are the same value in most cases.
• Sender Token:  This is given by CertainSafe to users.  If this field is not present in the message body, the adapter will use the value provided here.  The Sender and Merchant tokens are the same value in most cases.
• Concurrent Connections:  This sets the number of allowable concurrent connections to CertainSafe.
• Send Timeout:  A value, in seconds, in which a call to CertainSafe will timeout.

Adapter Modes

The CertainSafe adapter only supports SolicitResponse mode since the information given in the response message from each CertainSafe operation is important.  In SolicitResponse mode, the adapter will listen for messages sent over the bus to the topic chosen.  Neuron will expect a response from CertainSafe when the message received from the bus is sent by the adapter.  Furthermore, the semantic for that message should be set to “request”.  CertainSafe will automatically send back a response to the message sent that contains the item, the token used to retrieve the stored information, and/or information on any errors that occurred.

Messaging

CertainSafe supports six operations.  They are storeVault, retrieveVault, updateVault, removeVault, storeVaultList, and retrieveVaultList.  Each operation is detailed below along with message body examples.  Also, example XML messages and schema definitions for each operation can be generated using the Metadata Generation wizard in Neuron.  The message body can be in XML or JSON formats and CertainSafe will return a response in the format that the message is sent in.  Furthermore, the header in the message body containing the two tokens and authentication Id is optional as long as the tokens and Id are set in the adapter properties or custom message properties.

Every CertainSafe message, when using XML, has a root element that follows the format “{requestName}Vault” or “{requestName}VaultList” if sending or retrieving a list of items where “{requestName}” is the name of the operation.  The root element contains two nodes.  The first node is the “header” element.  This contains the merchantToken, authenticationId, senderToken, and optionally the terimnalId elements.  The second element in the root is the request itself.  The name of that node is always the operation name (e.g. “<storeVaultRequest>” for the store operation).

For JSON messages, the JSON object is composed of two objects— a header and the request.  The header contains the two tokens and authentication Id along with an optional terminal Id object.  The request object is named after the operation name followed by request (e.g. “storeVaultRequest” for the store operation).

Header Elements

Store Vault and Update Vault Request Elements

Note: Update vault does not use the “shouldEncryptCustomData” element

Store Vault List Request Elements

Retrieve Vault, Retrieve Vault List, and Remove Vault Request Elements

Note: Retrieve vault list and remove vault do not use the “shouldDecryptCustomData” element

Sample Messages and Operations

storeVault

Used to store a single item in the CertainSafe vault.

XML:

<?xml version="1.0" encoding="utf-8" ?>

<storeVaultRequestMessage>

<header>

<merchantToken>00000000-0000-0000-0000-000000000000</merchantToken>

<authenticationId>YourAuthenticationId</authenticationId>

<senderToken>00000000-0000-0000-0000-000000000000</senderToken>

</header>

<storeVaultRequest>

<itemType>AccountNumber</itemType>

<name>Jane Smith</name>

<customerNumber>JS-001</customerNumber>

<expirationDate>1115</expirationDate>

<textItem>4000300020001000</textItem>

<custom1>Custom 1</custom1>

<custom2>Custom 2</custom2>

<custom3>Custom 3</custom3>

</storeVaultRequest>

</storeVaultRequestMessage>

JSON:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"StoreVaultRequest":

{"ItemType":"EmailAddress",

"TextItem":"ss@sally.smith.com",

"CustomerNumber":"SomeCustomer-634967794668316210",

"Name":"Sally Smith",

"Custom1":"Custom data 1",

"Custom2":"Custom data 2",

"Custom3":"Custom data 3"}

}

retrieveVault

Used to retrieve a single item from the CertainSafe vault.

XML:

<?xml version="1.0" encoding="utf-8" ?>

<retrieveVaultRequestMessage>

<header>

<merchantToken>00000000-0000-0000-0000-000000000000</merchantToken>

<authenticationId>YourAuthenticationId</authenticationId>

<senderToken>00000000-0000-0000-0000-000000000000</senderToken>

<terminalId>000</terminalId>

</header>

<retrieveVaultRequest>

<token>001UPV2Cs9EnRM11</token>

</retrieveVaultRequest>

</retrieveVaultRequestMessage>

JSON:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"RetrieveVaultRequest":

{"Token":"001UT0EfPA159d3X"}

}

updateVault

Used to update an item in the CertainSafe vault.

XML:

<?xml version="1.0" encoding="utf-8" ?>

<updateVaultRequestMessage>

<header>

<merchantToken>00000000-0000-0000-0000-000000000000</merchantToken>

<authenticationId>YourAuthenticationId</authenticationId>

<senderToken>00000000-0000-0000-0000-000000000000</senderToken>

<terminalId>000</terminalId>

</header>

<updateVaultRequest>

<token>001UPV2Cs9EnRM11</token>

<itemType>AccountNumber</itemType>

<name>Jane Smith-Jones</name>

<textItem>4001300120011001</textItem>

<custom1>Custom 1 - new</custom1>

<custom2>{{CLEAR}}</custom2>

<custom3>Custom 3 - new</custom3>

</updateVaultRequest>

</updateVaultRequestMessage>

JSON:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"UpdateVaultRequest":

{"Token":"001UT0EfPA159d3X",

"TextItem":"546-22-3333",

"Name":"Sally Smith",

"Custom1":"A01",

"Custom2":"A02",

"Custom3":null}

}

removeVault

Used to delete an item from the CertainSafe vault.

XML:

<?xml version="1.0" encoding="utf-8" ?>

<removeVaultRequestMessage>

<header>

<merchantToken>00000000-0000-0000-0000-000000000000</merchantToken>

<authenticationId>YourAuthenticationId</authenticationId>

<senderToken>00000000-0000-0000-0000-000000000000</senderToken>

<terminalId>000</terminalId>

</header>

<removeVaultRequest>

<token>001UPV2Cs9EnRM11</token>

</removeVaultRequest>

</removeVaultRequestMessage>

JSON:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"RemoveVaultRequest":

{"Token":"001UT0EfPA159d3X"}

}

storeVaultList

Used to store a list of items in the CertainSafe vault.

XML:

<?xml version="1.0" encoding="utf-8" ?>

<storeVaultListRequestMessage>

<header>

<merchantToken>00000000-0000-0000-0000-000000000000</merchantToken>

<senderToken>00000000-0000-0000-0000-000000000000</senderToken>

<authenticationId>YourAuthenticationId</authenticationId>

</header>

<storeVaultListRequest>

<itemType>EmailAddress</itemType>

<newVaultItem>

<dataItem>ema_000001@myemail.com</dataItem>

<correlationId>id_000001</correlationId>

</newVaultItem>

<newVaultItem>

<dataItem>ema_000002@myemail.com</dataItem>

<correlationId>id_000002</correlationId>

</newVaultItem>

<newVaultItem>

<dataItem>ema_000003@myemail.com</dataItem>

<correlationId>id_000003</correlationId>

</newVaultItem>

</storeVaultListRequest>

</storeVaultListRequestMessage>

JSON:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"StoreVaultListRequest":

{"ItemType":"EmailAddress",

"NewVaultItem":

[{"DataItem":"ema_000001@myemail.com",

"CorrelationId":"id_000001"},

{"DataItem":"ema_000002@myemail.com",

"CorrelationId":"id_000002"},

{"DataItem":"ema_000003@myemail.com",

"CorrelationId":"id_000003"}]

}

}

retrieveVaultList

Used to retrieve a list of items from the CertainSafe vault.

XML:

<?xml version="1.0" encoding="utf‐8"?>

<retrieveVaultListRequestMessage>

<header>

<merchantToken>00000000‐0000‐0000‐0000‐000000000000</merchantToken>

<senderToken>00000000‐0000‐0000‐0000‐000000000000</senderToken>

<authenticationId>YourAuthenticationId</authenticationId>

</header>

<retrieveVaultListRequest>

<token>001UT0JZysu4CX7C</token>

<token>001UT0JZysu4CX7M</token>

<token>001UT0JZysu4CX7b</token>

<token>001UT0JZysu4CX7n</token>

<token>001UT0JZysu4CX7A</token>

<token>001UT0JZysu4CX7P</token>

<token>001UT0JZysu4CX79</token>

<token>001UT0JZysu4CX7q</token>

<token>001UT0JZysu4CX78</token>

<token>001UT0JZysu4CX7R</token>

</retrieveVaultListRequest>

</retrieveVaultListRequestMessage>

JSON:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

RetrieveVaultListRequest":

{"Token":

["001UT0JZysu4CX7C",

"001UT0JZysu4CX7M",

"001UT0JZysu4CX7b",

"001UT0JZysu4CX7n",

"001UT0JZysu4CX7A",

"001UT0JZysu4CX7P",

"001UT0JZysu4CX79",

"001UT0JZysu4CX7q",

"001UT0JZysu4CX78",

"001UT0JZysu4CX7R"]

}

}

Use Cases

Store an email address

Request:

<?xml version="1.0" encoding="utf-16"?>

<storeVaultRequestMessage xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">

<header xmlns="https://www.neuronesb.com/CertainSafe/Header">

<merchantToken>00000000‐0000‐0000‐0000‐000000000000</merchantToken>

<authenticationId>Your Authentication Id</authenticationId>

<senderToken>00000000‐0000‐0000‐0000‐000000000000</senderToken>

</header>

<storeVaultRequest>

<itemType>EMailAddress</itemType>

<name>John Doe</name>

<customerNumber>1</customerNumber>

<expirationDate>1020</expirationDate>

<textItem>johndoe@email.com</textItem>

<documentItem>johndoe@email.com</documentItem>

<shouldEncryptCustomData>false</shouldEncryptCustomData>

</storeVaultRequest>

</storeVaultRequestMessage>

Response:

<storeVaultResultResponse>

<status>

<transactionCompleted>true</transactionCompleted>

<message>Transaction successful.</message>

<resultCode>000</resultCode>

<dataValidationError>

<timeStamp>2016/02/25 22:12:04</timeStamp>

</dataValidationError>

</status>

<storeVaultResult>

<token>TokenOfItem</token>

<itemType>EMailAddress</itemType>

<name>John Doe</name>

<customerNumber>1</customerNumber>

</storeVaultResult>

</storeVaultResultResponse>

Retrieve an email address/item

Request:

<?xml version="1.0" encoding="utf-16"?>

<retrieveVaultRequestMessage xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="https://www.neuronesb.com/CertainSafe/RetrieveVault">

<header xmlns="https://www.neuronesb.com/CertainSafe/Header">

<merchantToken>00000000‐0000‐0000‐0000‐000000000000</merchantToken>

<authenticationId>Your Authentication Id</authenticationId>

<senderToken>00000000‐0000‐0000‐0000‐000000000000</senderToken>

</header>

<retrieveVaultRequest>

<token>TokenOfItem</token>

</retrieveVaultRequest>

</retrieveVaultRequestMessage>

Response:

<?xml version="1.0" encoding="utf-16"?>

<retrieveVaultResultResponse>

<status>

<transactionCompleted>true</transactionCompleted>

<message>Transaction successful.</message>

<resultCode>000</resultCode>

<dataValidationError>

<timeStamp>2016/05/10 23:15:30</timeStamp>

</dataValidationError>

</status>

<retrieveVaultResult>

<vaultItem>

<itemType>EMailAddress</itemType>

<textItem>johndoe@email.com</textItem>

<documentItem>johndoe@email.com</documentItem>

<name>John Doe</name>

<token>TokenOfItem</token>

<customerNumber>1</customerNumber>

<expirationDate>1020</expirationDate>

</vaultItem>

</retrieveVaultResult>

</retrieveVaultResultResponse>

Update an item

Request:

<?xml version="1.0" encoding="utf-16"?>

<updateVaultRequestMessage xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">

<header xmlns="https://www.neuronesb.com/CertainSafe/Header">

<merchantToken>00000000‐0000‐0000‐0000‐000000000000</merchantToken>

<authenticationId>Your Authentication Id</authenticationId>

<senderToken>00000000‐0000‐0000‐0000‐000000000000</senderToken>

<terminalId>001</terminalId>

</header>

<updateVaultRequest>

<token>TokenOfItem</token>

<itemType>EMailAddress</itemType>

<name>James Doe</name>

<customerNumber>1</customerNumber>

<expirationDate>1020</expirationDate>

<textItem>jamesdoe@email.com</textItem>

<documentItem>jamesdoe@email.com</documentItem>

<custom1>custom11</custom1>

</updateVaultRequest>

</updateVaultRequestMessage>

Response:

<?xml version="1.0" encoding="utf-16"?>

<updateVaultResultResponse>

<status>

<transactionCompleted>true</transactionCompleted>

<message>Transaction successful.</message>

<resultCode>000</resultCode>

<dataValidationError>

<timeStamp>2016/03/09 18:20:45</timeStamp>

</dataValidationError>

</status>

<updateVaultResult>

<token>TokenOfItem</token>

<itemType>EMailAddress</itemType>

<name>James Doe</name>

<customerNumber>1</customerNumber>

<custom1>custom11</custom1>

</updateVaultResult>

</updateVaultResultResponse>

Store a List of Items

Request:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"StoreVaultListRequest":

{"ItemType":"EmailAddress",

"NewVaultItem":

[{"DataItem":"ss@sally.smith.com",

"CorrelationId":"SomeCustomer-634967794668316210"},

{"DataItem":"johndoe@email.com",

"CorrelationId":"2"}]

}

}

Response:

{"Data":

{"ReturnedItem":

[{"ItemType":null,

"Item":null,

"CorrelationId":" SomeCustomer-634967794668316210",

"Token":"TokenOfItem1",

"DecryptionError":false},

{"ItemType":null,

"Item":null,

"CorrelationId":"2",

"Token":"TokenOfItem2",

"DecryptionError":false}],

"TotalItemCount":2},

"Status":

{"TransactionCompleted":true,

"Message":"Transaction successful.",

"ResultCode":"000",

"DataValidationError":

{"TimeStamp":null,

"ClientTransactionIdentifier":null,

"TransactionIdentifier":null,

"DataValidationErrorDetails":[],

"ObjectType":null

},

ExceptionToken":null

}

}

Retrieve a List of Items

Request:

{"Header":

{"MerchantToken":"00000000‐0000‐0000‐0000‐000000000000",

"SenderToken":"00000000‐0000‐0000‐0000‐000000000000",

"AuthenticationId":"Your Authentication Id"},

"RetrieveVaultListRequest":{"Token":

["TokenOfItem1",

"TokenOfItem2"]}

}

Response:

{"Data":

{"ReturnedItem":

[{"ItemType":"EMailAddress",

"Item":"ss@sally.smith.com",

"CorrelationId":"SomeCustomer-634967794668316210",

"Token":"TokenOfItem1",

"DecryptionError":false},

{"ItemType":"EMailAddress",

"Item":"johndoe@email.com",

"CorrelationId":"2",

"Token":"TokenOfItem2",

"DecryptionError":false}]},

"Status":

{"TransactionCompleted":true,

"Message":"Transaction successful.",

"ResultCode":"000",

"DataValidationError":

{"TimeStamp":"2016/05/11 15:30:11",

"ClientTransactionIdentifier":null,

"TransactionIdentifier":null,

"DataValidationErrorDetails":[],

"ObjectType":null},

"ExceptionToken":null}

}

Remove/Delete an Item

Request:

{"Header":

{"MerchantToken":"0000000-0000-0000-0000-000000000000",

"SenderToken":"00000000-0000-0000-0000-000000000000",

"AuthenticationId":"Your Authentication Id"},

"RemoveVaultRequest":

{"Token":"TokenOfItem"}

}

Response:

{"Data":

{"Token":"TokenOfItem”},

"Status":

{"TransactionCompleted":true,

"Message":"Transaction successful.",

"ResultCode":"000",

"DataValidationError":

{"TimeStamp":null,

"ClientTransactionIdentifier":null,

"TransactionIdentifier":null,

"DataValidationErrorDetails":[],

"ObjectType":null},

"ExceptionToken":null

}

}

Context Properties

In addition to setting the sender token, merchant token, and authentication Id in the message body, these can also be set in the custom properties of the message.  The priority of how the sender token, merchant token, and authentication Id are set is as follows:

1. From the header in the message body
2. From the custom properties of the message
3. From the values set in the adapter’s properties

For example, if a message did not have the header in the message body containing the two tokens and authentication Id, they would be set from the custom properties of the message.  If they are not in the custom properties, then they would be set from the values in the adapter’s properties panel in Neuron.  If they are missing completely, the adapter will throw an error.  Also, if just one or two of the two tokens or authentication Id are missing from the header in the message body, the adapter will try to find them in the custom properties and then, if missing from there, the values in the adapter’s properties.  Here are the custom properties that can be set:

1. certainsafe.AuthenticationId
2. certainsafe.MerchantToken
3. certainsafe.SenderToken

“certainsafe” is considered the prefix and what follows the dot is considered the property name.

Metadata Generation Wizard

The Metadata Generation Wizard is a tool that is used to generate sample XML messages and XSD schema definitions for certain adapters and their operations.  The following guide assumes the user has a CertainSafe adapter registered and an adapter endpoint already configured.

The first step is to click the “Generate” button (outlined in red in the picture below) in the main panel of Neuron ESB Explorer.  The button can be accessed from any of the following menus:

In the “Repository” tab in:

XML Schemas

XSL Transformations

XML Documents

Text Documents

Json Documents

Swagger Documents

In the Connections tab in:

Adapter Registration

Adapter Endpoints

Click the “Next” button and choose an adapter and adapter endpoint.  In this case, choose the CertainSafe adapter and the endpoint that has been configured for the adapter.  Click “Next”.  Expand the “Vault Operations” menu item and choose “Vault”.  Next, choose the operation that is desired and click “Add”.  More than one operation can be added by choosing each operation and adding it to the list.

Click “Next”.  Choose whether to generate sample XML messages (chosen by default) and whether to overwrite the existing documents, if they have already been added, by clicking on the appropriate boxes.

Click “Next” to review the documents that will be generated.  Finally, click finish to generate the documents.

Troubleshooting

Issue:	Resolution:
An exception of type “Exception” is thrown along with the message “CertainSafe Adapter: the ESB message body is not in a correct format (XML or JSON).  See xml samples from the metadata generation wizard for sample messages.”	Make sure the message body is in XML or JSON format.  The adapter checks to see if the message begins with a “{“ or “<” which denotes JSON or XML, respectively.
An exception of type “Exception” is thrown along with the message “The request in the ESB message is invalid.”	Make sure that the JSON request is spelled correctly in the message body and that it is one of the six requests supported (i.e. “StoreVaultRequest”, “StoreVaultListRequest”, “RetrieveVaultRequest”, “RetrieveListVaultRequest”, “UpdateVaultRequest”,“RemoveVaultRequest”)
An exception of type “Exception” is thrown along with the message “The XML root element in the ESB message is invalid.”	Make sure that the XML root element is spelled correctly in the message body and that it is one of the six requests supported (i.e. “storeVaultRequestMessage”, “storeVaultListRequestMessage”, “retrieveVaultRequestMessage”, “retrieveListVaultRequestMessage”, “updateVaultRequestMessage”,“removeVaultRequestMessage”)
An exception of type “Exception” is thrown along with the message “Message header is invalid.”	Make sure that the message’s XML header element contains only a combination of the following elements: “merchantToken”, “senderToken”, “authenticationId”, “terminalId”