Signature Authentication

Generate Public/Private key pair

The following commands will generate a ECDSA (secp256k1) private/public key pair in the directory it is run. openssl must be installed on the machine before running.

NOTE: This step is not needed for verifying webhooks. Instead you will use UTB's public key provided to you.

openssl ecparam -name secp256k1 -genkey -noout -out utb-private-key.pem
openssl ec -in utb-private-key.pem -pubout > utb-public-key.pem

The public key must be zipped and sent to your UTB contact to finish setting up you API subscription.

Required Headers

The following headers must be set for every request:

• Date
• X-UTB-Subscription-Key
• X-UTB-Signature-Nonce
• X-UTB-Signature-Version
• X-UTB-Signature

Date

Standard HTTP header that must follow HTTP standards for formatting.

Date: Wed, 21 Oct 2015 07:28:00 GMT

X-UTB-Subscription-Key

Either the primary or secondary subscription key. This will be provided by UTB.

X-UTB-Signature-Nonce

The nonce must be a single use generated value. We suggest using UUID/GUID for this field. Each request must use a different nonce.

X-UTB-Signature-Version

Represents the version of signature authentication being used. Valid values: v1

X-UTB-Signature

To calculate the signature of your request:

1. Concatenate the request body, Date header value, and X-UTB-Signature-Nonce header value.
2. Digitally sign using your private key and the SHA256withECDSA algorithm
   • Cryptography libraries can usually compute digital signatures, however, to do it manually:
     1. Hash the raw signature with HMAC256
     2. Encrypt the hashed signature with your ECDSA secp256k1 private key

Webhook Events and Signatures

To verify the signature of a webhook event sent to you from UTB's servers, we follow similar steps to generating signatures for requests to the UTB API.

UTB Public Key

Send an email to [email protected] to request a copy of UTB's ECDSA secp256k1 public key.

Verification

If using a cryptography library that has a verify signature method:

1. Concatenate the webhook request body, Date header value, and X-UTB-Signature-Nonce header value.
2. Provide the value in step 1 to the library method as the input, the UTB ECDSA secp256k1 public key as the key, and the signature in the X-UTB-Signature header as the signature.

If verifying manually:

1. Decrypt the request signature in the X-UTB-Signature header with the UTB ECDSA secp256k1 public key.
2. Concatenate the webhook request body, Date header value, and X-UTB-Signature-Nonce header value.
3. Hash the value from step 2 with HMAC256
4. Compare the hashed value from step 3 and the decrypted header in step 1. If they match, the request is verified.