[−][src]Function bronco::decode

pub fn decode(token: &str, key: &[u8], ttl: u32) -> Result<String, DecodeError>

Decodes a Bronco token to a string payload, given a 256 bit (i.e. 32 byte) secret key.

token - Bronco token to be decoded to a string.

key - 32 byte secret key.

ttl - TTL in seconds, used to treat the token as expired if has a timestamp more than TTL seconds in the past. If ttl is 0, the check is not performed.

Decoding is done by performing the following steps, in order:

  1. Verify that token is at least 60 characters long.
  2. Base64 (URL-safe variant) decode token.
  3. Verify that version (the first byte of the decoded token) is 0x01.
  4. Extract the header (the first 29 bytes) from the decoded token.
  5. Extract the nonce (the last 24 bytes of `header) from the header.
  6. Decrypt and verify the ciphertext|tag combination with IETF XChaCha20-Poly1305 AEAD using the secret key and nonce. header is used as the additional data.
  7. Extract timestamp (bytes 2 to 5) from header.
  8. Verify that timestamp is less than ttl seconds in the past (if ttl is greater than 0).

Example

use bronco::decode;

// let key: &[u8] = ...;
// let token: &str = ...;
let ttl = 60; // token expires 1 minute after creation
let message: String = decode(token, key, ttl).unwrap();
assert_eq!(message, "hello, world!");

Errors

Returns TokenTooShort if the token is less than 60 characters long (minimum length of an encoded Bronco token).

Returns WrongKeyLength if the key is not exactly 32 bytes.

Returns Base64DecodeFailed if the token could not be Base64 decoded.

Returns InvalidVersion if the version byte of the token is not equal to 0x01.

Returns VerificationFailed if the ciphertext|tag pair could not be decrypted and verified.

Returns TtlTooLarge if the current UNIX timestamp + ttl seconds is too far in the future.

Panics

Panics if the current system time is before UNIX epoch (due to anomalies such as the system clock being adjusted backwards).