Struct CredentialsToken

Source

pub struct CredentialsToken(/* private fields */);

Available on crate feature transport only.

Expand description

A credentials token: the shared secret two platforms authenticate each other with.

token: The credentials token for the other party to authenticate in your system. It should only contain printable non-whitespace ASCII characters, that is, characters with Unicode code points from the range of U+0021 up to and including U+007E.

This type exists so that a credentials token is hard to leak:

Debug and Display print Token(****ab12), never the secret. A token that ends up in a tracing span, a panic message or a serialised error is therefore not a disclosure.
PartialEq compares in constant time, so a server that looks a token up by comparing against known tokens does not leak its contents through timing.
The buffer is zeroised when the token is dropped.
There is no Serialize: a token reaches the wire only through CredentialsToken::to_header_value, or as the Credentials.token field of a credentials object, which is the one place the protocol puts it in a body.

use ocpi_kit::transport::CredentialsToken;

let token = CredentialsToken::new("example-token").unwrap();
assert_eq!(token.to_header_value(), "Token ZXhhbXBsZS10b2tlbg==");
assert_eq!(format!("{token:?}"), "Token(****oken)");

Spec: 2.3.0 §transport_and_format_authorization_header, §credentials_credentials_object

Implementations§

Source §

impl CredentialsToken

Source

pub const MAX_LEN: usize = 64

The maximum length the spec gives: string(64).

Source

pub fn new(value: impl Into<String>) -> Result<Self, InvalidToken>

Creates a token, enforcing the character set and length the spec gives.

§Errors

Returns InvalidToken if the value is empty, longer than 64 characters, or contains a character outside U+0021..=U+007E — which notably excludes the space.

Source

pub fn new_lenient(value: impl Into<String>) -> Self

Creates a token without enforcing anything, for values read off the wire.

Source

pub fn generate() -> Self

Generates a fresh random token.

Produces a hyphenated UUID v4, which is what the specification’s own examples use and what the vast majority of implementations do.

Source

pub fn expose_secret(&self) -> &str

The token in cleartext.

Named to be conspicuous at a call site: everything else about this type is designed to stop the secret escaping by accident.

Source

pub fn to_credentials_field(&self) -> OcpiString<64>

The token as the string(64) that goes into a Credentials object body.

Source

pub fn to_header_value(&self) -> String

The full Authorization header value, Base64-encoded as the spec requires.

After the literal ‘Token’, there SHALL be one space, followed by the ‘encoded token’. The encoded token is obtained by encoding the credentials token to an octet sequence with UTF-8 and then encoding that octet sequence with Base64 according to RFC 4648.

Source

pub fn to_header_value_unencoded(&self) -> String

The Authorization header value without Base64, for pre-2.2-d2 peers.

NOTE: Many OCPI 2.1.1 and 2.2 implementations do not Base64 encode the credentials token when including it in the ‘Authorization’ header. … Implementations that wish to be compatible with non-encoding 2.1.1 and 2.2 implementations have to choose the right way to parse and write authorization headers by either trial and error or configuration flags.

This crate chooses configuration flags: see Quirks::send_unencoded_token.

Source

pub fn parse_header( value: &str, accept_unencoded: bool, ) -> Result<Self, InvalidToken>

Parses an Authorization header value.

Both encodings are accepted: the value is Base64-decoded when that yields a valid token, and otherwise taken literally. accept_unencoded gates the fallback — leave it off for a peer that is known to encode properly, so that a mangled header is an error rather than a token nobody recognises.

§Errors

Returns InvalidToken if the value does not start with Token , or if what follows is neither valid Base64 of a token nor (when allowed) a bare token.

Source

pub fn is_conformant(&self) -> bool

Whether this value satisfies the character set and length the spec gives.

Source

pub fn hint(&self) -> String

A stable, non-reversible fingerprint, for logging and correlating without disclosure.

This is the last four characters of the token, which is what the redacted Debug shows. It is a debugging aid, not a secret-safe identifier for a short token.