Message Signing & Verification

Spark Messages are signed using a private key to create a digital signature. External applications can then verify this signature with a public key.

To verify a Spark message, you need the following three things:

1. Public Key
2. Message Signature
3. The String-to-verify

Retrieving the Public Key

Section link for Retrieving the Public Key

1. Retrieve the Vault certificate ID from the received message header, X-VaultAPISignature-CertificateId.
2. Use this Certificate ID as input for a Vault API call to Retrieve the Signing Certificate. This call returns the public key as a .pem file.

GET /api/{version}/services/certificate/{X-VaultAPISignature-CertificateId}

Note that message headers such as X-VaultAPISignature-CertificateId may show in a different case depending on the receiving host, so developers should be prepared to handle the headers as case-insensitive.

Retrieving the Message Signature

Section link for Retrieving the Message Signature

For Vaults on version 20R1.0, the message signature is from the request header X-VaultAPI-Signature.

For Vaults on version 20R1.2+, the message signature is from the request header X-VaultAPI-SignatureV2.

Creating the String-to-Verify

Section link for Creating the String-to-Verify

The String-to-verify must be in the following format:

• All X-VaultAPISignature-* headers in the request must be in the following format: Lowercase(<HeaderName1>)+":"+Trim(<value>)+"\n"

  • Each header name-value pair must be separated by the newline character (\n)
  • Header names must be in lower case
  • Header name-value pairs must not contain any spaces
  • Header names must be sorted alphabetically

• The JSON object in the HTTP body of the request must be raw text

• Add a newline character after the HTTP body, followed by the full HTTPS URL as received by your external service. Make sure this also includes any query parameters.

• The following is an example of a Spark Message in String-to-verify format:

  Copy to clipboard

  x-vaultapisignature-certificateid:00001 x-vaultapisignature-executionid:a123bede-32cb-4dbc-a7d9 x-vaultapisignature-requestdatetime:2012-04-25T21:49:27.719Z x-vaultapisignature-requestid:ffjkek809809fjklkfjlkjf89 x-vaultapisignature-requestnotafter:2012-04-25T21:54:27.719Z x-vaultapisignature-requestnotbefore:2012-04-25T21:48:27.719Z x-vaultapisignature-requesttype:spark_message x-vaultapisignature-url:https//www.etech.com/services/vaultmessage x-vaultapisignature-vaultid:1000023 { "vault_name" : "Megatech RIM Vault", "vault_host_name" : "biorad-rim.veevavault.com", "queue_name" : "study_sync_with_med_innovation__c", "enter_queue_timestamp" : "2012-04-25T21:49:25.719Z", "send_message_timestamp" : "2012-04-25T21:49:27.719Z", "send_attempt" : 2, "message_id" : "bb28d4ca-3a37-4fef-91ae-93c3a4ec1d8d", "message" : { "attributes": { "object" : "product_brand__c", "has_related" : true, "related_count" : 100, "authorization" : "A109315AC45D0FA76A5891FE25B2FCBB1AEBDBDDF 25008682BEC50BF43F5DD9A96700A962515703060 53E4571108799F7141A1857A571786AEF5A626655 7B380" }, "items": [ "OP0000000010I13", "OP0000000000I09", "OP0000000022T06" ] } } https//www.etech.com/services/vaultmessage?id=1234

Verifying Message Signature

Section link for Verifying Message Signature

Once you have all three necessary pieces of information, you can use your digital signature library in your application platform to verify the signature. You can see an example of this in our code samples.