Signatures v15

The security of the requests sent to the Upvest Investments API is ensured by the fact that all requests are signed with a signature algorithm that is defined in the IETF draft for HTTP Message Signatures v15.

This tutorial guides you through the necessary steps to implement HTTP signatures.

How HTTP signatures work

How to enable v15

To be able to make a request with v15 of signing, add the following version header:

Example version header

X-Signing-Proxy-Version: 15

HTTP request format

To be able to sign a request, the format of the request must contain all mandatory headers.

HTTP request body content-digest

For all requests that contain a body, the body content-digest must be calculated and added as a request header named content-digest, as described in the IETF draft for HTTP digest fields.

In summary, the digest calculation algorithm as used for the Investment API can be applied as follows:

• Capture the entire request body's byte stream.
• Calculate the SHA-512 hash of the body content.
• Encode the resulting value using Base64 encoding
• Add a request header named content-digest with this value: sha-512=:{digest value}:, where {digest value} is replaced by the result of the previous step.

Example

Signatures

The Investment API uses a strict configuration of the HTTP message signatures calculation algorithm and requires particular request components to be included in the signature calculation process.

The request signature is transported via two HTTP headers that must be present in all API requests:

Signature headers

Signature components

To calculate the signature value for the request, the caller must prepare the signature input string and generate a signature of this input string with one of the supported signing algorithms.

The signature input string consists of several components, each of which is defined as a key-value pair. For each component, the key and the value are separated by a colon followed by a space.

Example

component-key: component-value

To calculate the signature for a request to the Investment API, use the following list of components:

Metadata of the @signature-params component

The component @signature-params contains signature metadata. Since they consist of several parts, they are connected by a semicolon (;) as a separator. The metadata consists of the following parts:

Example

@signature-params: ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "content-digest" "idempotency-key" "upvest-client-id"); keyid = "8d4997a8-cf7a-4e51-adbb-401656a3e5c2"; created = 1633529659; expires = 1633529664; nonce = "o085M4cMgpbicuOL"

How to calculate the signature

After all signature components are defined along with the @signature-paramscomponent, the following signature header values can be calculated.

Signature header values

Example signature input

signature-input: sig1 = ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "content-digest" "idempotency-key" "upvest-client-id"); keyid ="8d4997a8-cf7a-4e51-adbb-401656a3e5c2"; created = 1633529659; expires = 1633529664;nonce = "o085M4cMgpbicuOL"

Calculating the signature value

To calculate the signature value, proceed as follows:

1. Take all signature components in the same order as the component keys listed in @signature-params.

2. Add the @signature-params component to this list (even though it is not explicitly listed as a signature component in @signature-params itself).

3. Merge them using the new line character as a delimiter - \n.

Example signature input string

"@method": POST
"@path"": /endpoint
"@query": ?a=b
"accept": application/json
"authorization": Bearer access-token
"content-length": 16
"content-type": application/json
"content-digest": sha-512=:Hd9/AvGZkbjitW1+Ml8Fg1ux1mtcDYe6mLQjDyoowIWa3LM/PmwN2v9O+MjtQGrCA3EQWUL54dlgxKHyYbrucw==:
"idempotency-key": 2133825797664cad
"upvest-client-id": 5ec16164-6173-461d-b90d-116d68f55b40
"@signature-params": ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "content-digest" "idempotency-key" "upvest-client-id");keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2";created=1633529659;expires=1633529664;nonce="o085M4cMgpbicuOL"

4. Calculate the signature using the signing key and then encode the resulting signature by using Base64 encoding.

Example signature header

signature: sig1=:MIGIAkIBwgt8M6z9WDdEoUOh/2c5zIQxKHfQalVKjepSGibcG2JD0PJ9FYOD65aq8L2FotNcDvWliJKFrdEwZNJCgMVrx7MCQgG8cMJ3dorHLDwmJpp93CdBRMujBWvIpL+dcVawRpzKXt6ZTNkuPLrHKOkKYRtVRyPrnBuG5T9A71VMGUOJFeo3oA==:

Implementing HTTP signatures

After you have calculated the signature, you will learn how to implement it in this section.

Note that here too, the individual steps are illustrated and explained with the help of an example, which is not generally valid.

Prerequisites

Assume we have the following HTTP request:

POST /endpoint?a=b HTTP/1.1
host: server
accept: application/json
authorization: Bearer access-token
content-Length: 16
content-Type: application/json
date: Wed, 06 Oct 2021 16:14:19 CEST
expires: Wed, 06 Oct 2021 16:14:24 CEST
idempotency-key: 2133825797664cad
upvest-client-id: 5ec16164-6173-461d-b90d-116d68f55b40

{"key": "value"}

We sign this HTTP request with this private key, identified by a keyid of 8d4997a8-cf7a-4e51-adbb-401656a3e5c2:

-----BEGIN EC PRIVATE KEY-----  
MIHcAgEBBEIB6l0asXau1p6aSOKHTIrVvCEFT6aIhbw99mbbDeEuwOq0MdZ75InO
1ElIh6w+q/acHXYdGH5JCDzPlj5qku9vI+qgBwYFK4EEACOhgYkDgYYABADiKUUw
QsnlgdjuAT2xSEKmQbv2oZV8kbb/Bc4xhIj1K3HyLBaaTSX5gdnRlqk24WkPeMIX
OkAtopnCjoz4ekO1UwCdEdd2ZcODDUXxbSppXDS/ewFVU+FntEckSdi4RXMq7AC5
avwt+3mpug6ydS+tUDjN58MBR4YPCe9HKwubxJFXdA==
-----END EC PRIVATE KEY-----

In order for a request to be correct, we assume the following requirements:

• The authentication and upvest-client-id headers are filled according to the 'Authentication' guide.
• The content-length and content-type headers are set based on availability of the request body.
• accept is set to one of the supported values according to the API specification.
• date is set to the date and time the message was created.
• Optional: The expires header is set to the date/time after which the response is considered out of date.
• Optional: The idempotency-key header is set.

1. Calculating the request digest

This step is required only for requests that contain a request body.

digest = "sha-512=:" + base64( sha512( request.body ) ) + ":"

The resulting value for our example looks as follows:

sha-512=:Hd9/AvGZkbjitW1+Ml8Fg1ux1mtcDYe6mLQjDyoowIWa3LM/PmwN2v9O+MjtQGrCA3EQWUL54dlgxKHyYbrucw==:

2. Generating random request nonce

We use a simple random method that gives us 16 random characters from a specified alphabet:

nonce = random( "A-Za-z0-9", 16 )

We get the following nonce:

nonce="o085M4cMgpbicuOL"

3. Defining timestamps

created= now().ToUnixTime()
expires= now().add(expiration_duration).ToUnixTime()

created = 1633529659
expires =1633529664

4. Calculating the signature components

Please, note that the keys for calculation the signature components are quoted.

"@method": POST
"@path": /endpoint
"@query": ?a=b
"accept": application/json
"authorization": Bearer access-token
"content-length": 16
"content-type": application/json
"content-digest": sha-512=:Hd9/AvGZkbjitW1+Ml8Fg1ux1mtcDYe6mLQjDyoowIWa3LM/PmwN2v9O+MjtQGrCA3EQWUL54dlgxKHyYbrucw==:
"idempotency-key": 2133825797664cad
"upvest-client-id": 5ec16164-6173-461d-b90d-116d68f55b40

5. Calculating the @signature-params component

"@signature-params": ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "content-digest" "idempotency-key" "upvest-client-id");keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2";created=1633529659;expires=1633529664;nonce="o085M4cMgpbicuOL"

6. Calculating the request signature

1. Combine the signature components with @signature-params in the signature input string by joining them with line breaks (\n):

"@method": POST
"@path": /endpoint
"@query": ?a=b
"accept": application/json
"authorization": Bearer access-token
"content-length": 16
"content-type": application/json
"content-digest": sha-512=:Hd9/AvGZkbjitW1+Ml8Fg1ux1mtcDYe6mLQjDyoowIWa3LM/PmwN2v9O+MjtQGrCA3EQWUL54dlgxKHyYbrucw==:
"idempotency-key": 2133825797664cad
"upvest-client-id": 5ec16164-6173-461d-b90d-116d68f55b40
"@signature-params": ("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "digest" "idempotency-key" "upvest-client-id");keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2";created=1633529659;expires=1633529664;nonce="o085M4cMgpbicuOL"

2. Calculate the signature using the signing key and encode it with Base64 encoding:

:MIGHAkIAoTnL0VRsu66l+nb91Dfhpq+Fr88fdiy+FgkuYjRjQh0IFROEUEjFQOj5tPu+Ms5Z4llhWhGSw602ZivIZWwum8gCQWPUTjp9zAT8KgkH1Dynxw0nmYHZPAOaLKT2mGZ1YI/o6OjBVy5RkdGVw80IWc0QM3XXeoyH7A+EKdJ2wvUAvBQp:

7. Add the signature and signature-input headers to the request

POST /endpoint?a=b HTTP/1.1
host: server
accept: application/json
authorization: Bearer access-token
content-length: 16
content-type: application/json
date: Wed, 06 Oct 2021 16:14:19 CEST
content-digest: sha-512=:Hd9/AvGZkbjitW1+Ml8Fg1ux1mtcDYe6mLQjDyoowIWa3LM/PmwN2v9O+MjtQGrCA3EQWUL54dlgxKHyYbrucw==:
expires: Wed, 06 Oct 2021 16:14:24 CEST
idempotency-key: 2133825797664cad
signature: sig1=:MIGHAkIAoTnL0VRsu66l+nb91Dfhpq+Fr88fdiy+FgkuYjRjQh0IFROEUEjFQOj5tPu+Ms5Z4llhWhGSw602ZivIZWwum8gCQWPUTjp9zAT8KgkH1Dynxw0nmYHZPAOaLKT2mGZ1YI/o6OjBVy5RkdGVw80IWc0QM3XXeoyH7A+EKdJ2wvUAvBQp:
signature-input: sig1=("@method" "@path" "@query" "accept" "authorization" "content-length" "content-type" "content-digest" "idempotency-key" "upvest-client-id");keyid="8d4997a8-cf7a-4e51-adbb-401656a3e5c2";created=1633529659;expires=1633529664;nonce="o085M4cMgpbicuOL"
upvest-client-id: 5ec16164-6173-461d-b90d-116d68f55b40

{"key": "value"}

Supported signing key algorithms

For the signature verification, the Investment API supports the following algorithms:

ECDSA

The supported version of the ECDSA signing algorithm uses the P-521 curve and SHA-512 hashing link.

Private key generation with password protection as supported by the HTTP signature proxy:

openssl ecparam -genkey -name secp521r1 -outform PEM | openssl ec -aes256 -inform PEM -outform PEM -out ecdsa521.priv

Alternatively, but less secure (and not supported by the HTTP signature proxy), you can generate the private key without encrypting it:

openssl ecparam -genkey -name secp521r1 -outform PEM -out ecdsa521-unencrypted.priv

You can then encrypt it in a separate step after creation:

openssl ec -aes256 -inform PEM -outform PEM -in ecdsa521-unencrypted.priv -out ecdsa521.priv

Public key extraction:

openssl pkey -pubout -in ecdsa521.priv > ecdsa521.pub

ED25519

ED25519 signing algorithm uses the Curve255191 curve and SHA-512 hashing link.

Private key generation with password protection:

openssl genpkey -algorithm ed25519 -aes256 -outform PEM -out ed25519.priv

Alternatively, but less secure, you can generate the private key without encrypting it:

openssl genpkey -algorithm ed25519 -outform PEM -out ed25519-unencrypted.priv

You can then encrypt it in a separate step after creation:

openssl pkey -aes256 -inform PEM -outform PEM -in ed25519-unencrypted.priv -out ed25519.priv

Public key extraction:

openssl pkey -pubout -in ed25519.priv > ed25519.pub

brew install openssl
/usr/local/opt/openssl@3/bin/openssl version

Base64 encoding

For all calculations of Base64 values, the Investment API uses Base64 encoding with the standard alphabet and padding as defined in RFC 4648 section 4. To validate your implementation use the following examples:

Examples: