Struct Header

#[non_exhaustive]
pub struct Header<T = Empty> {
    pub key_set_url: Option<String>,
    pub key_id: Option<String>,
    pub certificate_url: Option<String>,
    pub certificate_sha1_thumbprint: Option<Thumbprint<20>>,
    pub certificate_thumbprint: Option<Thumbprint<32>>,
    pub token_type: Option<String>,
    pub other_fields: T,
}

JWT header.

See RFC 7515 for the description of the fields. The purpose of all fields except token_type is to determine the verifying key. Since these values will be provided by the adversary in the case of an attack, they require additional verification (e.g., a provided certificate might be checked against the list of “acceptable” certificate authorities).

A Header can be created using Default implementation, which does not set any fields. For added fluency, you may use with_* methods:

use sha2::{digest::Digest, Sha256};

let my_key_cert = // DER-encoded key certificate
let thumbprint: [u8; 32] = Sha256::digest(my_key_cert).into();
let header = Header::empty()
    .with_key_id("my-key-id")
    .with_certificate_thumbprint(thumbprint);

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

key_set_url: Option<String>

URL of the JSON Web Key Set containing the key that has signed the token. This field is renamed to jku for serialization.

key_id: Option<String>

Identifier of the key that has signed the token. This field is renamed to kid for serialization.

certificate_url: Option<String>

URL of the X.509 certificate for the signing key. This field is renamed to x5u for serialization.

certificate_sha1_thumbprint: Option<Thumbprint<20>>

SHA-1 thumbprint of the X.509 certificate for the signing key. This field is renamed to x5t for serialization.

certificate_thumbprint: Option<Thumbprint<32>>

SHA-256 thumbprint of the X.509 certificate for the signing key. This field is renamed to x5t#S256 for serialization.

token_type: Option<String>

Application-specific token type. This field is renamed to typ for serialization.

other_fields: T

Other fields encoded in the header. These fields may be used by agreement between the producer and consumer of the token to pass additional information. See Sections 4.2 and 4.3 of RFC 7515 for details.

For the token creation and validation to work properly, the fields type must Serialize to a JSON object.

Note that these fields do not include the signing algorithm (alg) and the token content type (cty) since both these fields have predefined semantics and are used internally by the crate logic.

Implementations

impl Header

pub const fn empty() -> Header

Creates an empty header.

impl<T> Header<T>

pub const fn new(fields: T) -> Header<T>

Creates a header with the specified custom fields.

pub fn with_key_set_url(self, key_set_url: impl Into<String>) -> Header<T>

Sets the key_set_url field for this header.

pub fn with_key_id(self, key_id: impl Into<String>) -> Header<T>

Sets the key_id field for this header.

pub fn with_certificate_url( self, certificate_url: impl Into<String>, ) -> Header<T>

Sets the certificate_url field for this header.

pub fn with_certificate_sha1_thumbprint( self, certificate_thumbprint: impl Into<Thumbprint<20>>, ) -> Header<T>

Sets the certificate_sha1_thumbprint field for this header.

pub fn with_certificate_thumbprint( self, certificate_thumbprint: impl Into<Thumbprint<32>>, ) -> Header<T>

Sets the certificate_thumbprint field for this header.

pub fn with_token_type(self, token_type: impl Into<String>) -> Header<T>

Sets the token_type field for this header.

Trait Implementations

impl<T> Clone for Header<T>

where T: Clone,

fn clone(&self) -> Header<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Header<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Decode for Header<T>

where T: Decode,

fn decode<__CodecInputEdqy>( __codec_input_edqy: &mut __CodecInputEdqy, ) -> Result<Header<T>, Error>

where __CodecInputEdqy: Input,

Attempt to deserialise the value from input.

fn decode_into<I>( input: &mut I, dst: &mut MaybeUninit<Self>, ) -> Result<DecodeFinished, Error>

where I: Input,

Attempt to deserialize the value from input into a pre-allocated piece of memory.

fn skip<I>(input: &mut I) -> Result<(), Error>

where I: Input,

Attempt to skip the encoded value from input.

fn encoded_fixed_size() -> Option<usize>

Returns the fixed encoded size of the type.

impl<T> Default for Header<T>

where T: Default,

fn default() -> Header<T>

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for Header<T>

where T: Deserialize<'de>,

fn deserialize<__D>( __deserializer: __D, ) -> Result<Header<T>, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Encode for Header<T>

where T: Encode,

fn size_hint(&self) -> usize

If possible give a hint of expected size of the encoding.

fn encode_to<__CodecOutputEdqy>( &self, __codec_dest_edqy: &mut __CodecOutputEdqy, )

where __CodecOutputEdqy: Output + ?Sized,

Convert self to a slice and append it to the destination.

fn encode(&self) -> Vec<u8>

Convert self to an owned vector.

fn using_encoded<R, F>(&self, f: F) -> R

where F: FnOnce(&[u8]) -> R,

Convert self to a slice and then invoke the given closure with it.

fn encoded_size(&self) -> usize

Calculates the encoded size.

impl<T> PartialEq for Header<T>

where T: PartialEq,

fn eq(&self, other: &Header<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Serialize for Header<T>

where T: Serialize,

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> TypeInfo for Header<T>

where T: TypeInfo + 'static,

type Identity = Header<T>

The type identifying for which type info is provided.

fn type_info() -> Type

Returns the static type identifier for Self.

impl<T> EncodeLike for Header<T>

where T: Encode,

impl<T> Eq for Header<T>

where T: Eq,

impl<T> StructuralPartialEq for Header<T>