exoscale.itsdangerous — exoscale/itsdangerous 0.1.2

ItsDangerous signed token implementation. This namespace provides two main signatures: sign and verify, refer to their documentation for details. ItsDangerous uses a simple hmac-based scheme to sign credentials. It is widely used in the Python world, especially in Flask applications. See https://itsdangerous.palletsprojects.com/en/1.1.x/ for more details.

ItsDangerous revolves around tuples of [payload, timestamp, signature] or the untimed [payload, signature] alternative. In its URL safe variant, each element of the tuple is Base64 encoded. This is the only variant supported in this implementation.

When signing and verifying, ItsDangerous supports the addition of a somewhat misnamed salt, used to namespace signing. In this case, the key is derived by first hashing the salt. The derived key is then used to sign or verify payloads.

Knowledge that should be shared out-of-band between signers and verifiers:

• A secret key (K)
• A salt for namespacing (S)
• The selected hashing algorithm (A) (with functions HASH_A and HMAC_A)

For a payload P at timestamp T, signing consists of:

TOSIGN = T ? (B64(P) + '.' + B64(T)) : (B64(P))
B64(P) + TOSIGN + '.' + B64(HMAC_A(HASH_A(K, S), TOSIGN))

epoch clj

(epoch)

UNIX epoch in seconds

main-key clj

(main-key {:exoscale.itsdangerous/keys [private-keys private-key]})

Figure out which private-key to use from the config. Support either a single ::private-key for backward compatibility, or a collection of keys, in which case the first is selected.

parse-token clj

(parse-token s)

Split a ItsDangerous token into its constituent parts. Assume timestamp to be 0 when not provided. The string to sign is returned as well.

sign clj

(sign {:exoscale.itsdangerous/keys [algorithm salt timestamp payload]
       :or {algorithm :exoscale.itsdangerous/hmac-sha1 timestamp (epoch)}
       :as config})

(sign config payload)

(sign config payload timestamp)

Run the signature process for a payload, yields token as a string.

Needs at least ::algorithm, ::salt, ::private-key, and ::payload. ::algorithm, ::salt, and ::private-key are shared knowledge elements, to be agreed upon out-of-band, ::payload, the payload to sign as a string. If ::private-keys is provided instead of ::private-key, the first key in the collection is used to sign the payload.

Optionally accepts ::timestamp, defaulting to the UNIX epoch in seconds.

signature-for clj

(signature-for {:exoscale.itsdangerous/keys [algorithm salt] :as config}
               payload
               private-key)

Given a supported algorithm (::hmac-sha1 ::hmac-sha256), private key, and salt, compute the signature of a payload. Yields the signature in Base64.

signatures-for clj

(signatures-for {:exoscale.itsdangerous/keys [algorithm private-keys salt]
                 :as config}
                payload)

Yield all possible signatures for a payload, based on the config

verify clj

(verify {:exoscale.itsdangerous/keys [token algorithm salt max-age private-key]
         :or {algorithm :exoscale.itsdangerous/hmac-sha1}
         :as config})

(verify config token)

(verify config token max-age)

Run verification on a token, throwing if the signature is invalid or if the token's validity has expired. Yields the payload upon success.

Needs at least ::algorithm, ::salt, ::private-key, and ::token. ::algorithm, ::salt, and ::private-key are shared knowledge elements, to be agreed upon out-of-band, ::token, the token to verify.

Optionally accepts ::max-age, in which case token validity in time will be checked.