PROV Storage Web Service Authentication

POST /users requires no authentication.

POST /tokens handles authentication by using a username/password pair passed in the body of the request.

All other requests require a signature for authentication.

Signing Requests

Authentication Headers

To sign a request you must have a valid sessionToken obtained from a POST /tokens request. Signed requests must contain three headers for authentication:

sessionKey

The value is the sessionToken.key that corresponds to the sessionToken.token used to sign the request.

timestamp

The time of request in ISO 8601 format. For example, 2017-05-04T16:24:00.535Z.

signature

A signature constructed as described below.

Constructing the signature

The signature of a request is a SHA256 HMAC which is then encoded as a Base64 string. In pseudocode:

signature = BASE64_ENCODE(
  HMAC_SHA256(
    BYTES_OF(sessionToken.token), 
    BYTES_OF(stringToSign)
  )
)

where stringToSign is a string obtained by joining several strings related to the request using the newline character as a separator:

stringToSign = 
        sessionToken.key
        + '\n'
        + httpMethod
        + '\n'
        + 'pennprovenance.net'
        + '\n'
        + requestPath
        + '\n'
        + queryString
        + '\n'
        + timestamp
        + '\n'
        + encodedHashedPayload

and we define

sessionToken.key

The same string used in the sessionKey header mentioned above.

httpMethod

The request method in uppercase. E.g., 'GET'.

requestPath

The request path. E.g., '/prov/types/374'.

queryString

The request's query string if any or the empty string if none. E.g., 'creatorId=4&pageToken=10' or ''.

timestamp

The same string as used in the timestamp header mentioned above.

encodedHashedPayload

The Base64 encoding the SHA256 hash of the request's 'payload' where 'payload' is defined as

• the Base64 encoding of the MD5 sum of the file if uploading a file with POST /documents/content
• the request's body if the request has a body
• the empty string in all other cases.

Example

Here is a simple Python script which creates a signature for a DELETE /tokens/{sessionKey} request: