feat: custom header support

Add true support for custom headers with full backwards compatibility.

Author: dsykes16

examples/custom_header.rs

@@ -2,7 +2,9 @@ use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 
 use jsonwebtoken::errors::ErrorKind;
-use jsonwebtoken::{Algorithm, DecodingKey, EncodingKey, Header, Validation, decode, encode};
+use jsonwebtoken::{
+    Algorithm, DecodingKey, EncodingKey, Validation, decode_with_custom_header, encode, header,
+};
 
 #[derive(Debug, Serialize, Deserialize, Clone)]
 struct Claims {
@@ -11,6 +13,19 @@ struct Claims {
     exp: u64,
 }
 
+#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, Hash)]
+struct CustomHeader {
+    alg: Algorithm,
+    custom: String,
+    another_custom_field: Option<usize>,
+}
+impl header::FromEncoded for CustomHeader {}
+impl header::Alg for CustomHeader {
+    fn alg(&self) -> &Algorithm {
+        &self.alg
+    }
+}
+
 fn main() {
     let my_claims =
         Claims { sub: "b@b.com".to_owned(), company: "ACME".to_owned(), exp: 10000000000 };
@@ -19,11 +34,10 @@ fn main() {
     let mut extras = HashMap::with_capacity(1);
     extras.insert("custom".to_string(), "header".to_string());
 
-    let header = Header {
-        kid: Some("signing_key".to_owned()),
+    let header = CustomHeader {
         alg: Algorithm::HS512,
-        extras,
-        ..Default::default()
+        custom: "custom".into(),
+        another_custom_field: 42.into(),
     };
 
     let token = match encode(&header, &my_claims, &EncodingKey::from_secret(key)) {
@@ -32,7 +46,7 @@ fn main() {
     };
     println!("{:?}", token);
 
-    let token_data = match decode::<Claims>(
+    let token_data = match decode_with_custom_header::<CustomHeader, Claims>(
         &token,
         &DecodingKey::from_secret(key),
         &Validation::new(Algorithm::HS512),

src/decoding.rs

@@ -7,7 +7,7 @@ use crate::Algorithm;
 use crate::algorithms::AlgorithmFamily;
 use crate::crypto::JwtVerifier;
 use crate::errors::{ErrorKind, Result, new_error};
-use crate::header::Header;
+use crate::header::{Alg, FromEncoded, Header};
 use crate::jwk::{AlgorithmParameters, Jwk};
 #[cfg(feature = "use_pem")]
 use crate::pem::decoder::PemEncodedKey;
@@ -37,15 +37,16 @@ use crate::crypto::rust_crypto::{
 
 /// The return type of a successful call to [decode](fn.decode.html).
 #[derive(Debug)]
-pub struct TokenData<T> {
+pub struct TokenData<H, T> {
     /// The decoded JWT header
-    pub header: Header,
+    pub header: H,
     /// The decoded JWT claims
     pub claims: T,
 }
 
-impl<T> Clone for TokenData<T>
+impl<H, T> Clone for TokenData<H, T>
 where
+    H: Clone,
     T: Clone,
 {
     fn clone(&self) -> Self {
@@ -273,21 +274,40 @@ pub fn decode<T: DeserializeOwned + Clone>(
     token: impl AsRef<[u8]>,
     key: &DecodingKey,
     validation: &Validation,
-) -> Result<TokenData<T>> {
+) -> Result<TokenData<Header, T>> {
+    decode_with_custom_header(token, key, validation)
+}
+
+/// Decode and validate a JWT with a custom header
+///
+/// If the token or its signature is invalid, or the claims fail validation, this will return an
+/// error.
+pub fn decode_with_custom_header<H, T>(
+    token: impl AsRef<[u8]>,
+    key: &DecodingKey,
+    validation: &Validation,
+) -> Result<TokenData<H, T>>
+where
+    H: DeserializeOwned + Clone + FromEncoded + Alg,
+    T: DeserializeOwned + Clone,
+{
     let token = token.as_ref();
-    let header = decode_header(token)?;
 
-    if validation.validate_signature && !validation.algorithms.contains(&header.alg) {
+    let (signature, message) = expect_two!(token.rsplitn(2, |b| *b == b'.'));
+    let (payload, header) = expect_two!(message.rsplitn(2, |b| *b == b'.'));
+    let header = H::from_encoded(header)?;
+
+    if validation.validate_signature && !validation.algorithms.contains(header.alg()) {
         return Err(new_error(ErrorKind::InvalidAlgorithm));
     }
 
-    let verifying_provider = jwt_verifier_factory(&header.alg, key)?;
+    let verifying_provider = jwt_verifier_factory(header.alg(), key)?;
+    verify_signature_body(message, signature, &header, validation, verifying_provider)?;
 
-    let (header, claims) = verify_signature(token, validation, verifying_provider)?;
+    let decoded_claims = DecodedJwtPartClaims::from_jwt_part_claims(payload)?;
+    validate(decoded_claims.deserialize()?, validation)?;
 
-    let decoded_claims = DecodedJwtPartClaims::from_jwt_part_claims(claims)?;
     let claims = decoded_claims.deserialize()?;
-    validate(decoded_claims.deserialize()?, validation)?;
 
     Ok(TokenData { header, claims })
 }
@@ -332,10 +352,21 @@ pub fn decode_header(token: impl AsRef<[u8]>) -> Result<Header> {
     Header::from_encoded(header)
 }
 
+/// Decode only the custom header of a JWT without decoding or validating the payload
+pub fn decode_custom_header<H>(token: impl AsRef<[u8]>) -> Result<H>
+where
+    H: DeserializeOwned + Clone + Alg + FromEncoded,
+{
+    let token = token.as_ref();
+    let (_, message) = expect_two!(token.rsplitn(2, |b| *b == b'.'));
+    let (_, header) = expect_two!(message.rsplitn(2, |b| *b == b'.'));
+    H::from_encoded(header)
+}
+
 pub(crate) fn verify_signature_body(
     message: &[u8],
     signature: &[u8],
-    header: &Header,
+    header: &impl Alg,
     validation: &Validation,
     verifying_provider: Box<dyn JwtVerifier>,
 ) -> Result<()> {
@@ -351,7 +382,7 @@ pub(crate) fn verify_signature_body(
         }
     }
 
-    if validation.validate_signature && !validation.algorithms.contains(&header.alg) {
+    if validation.validate_signature && !validation.algorithms.contains(header.alg()) {
         return Err(new_error(ErrorKind::InvalidAlgorithm));
     }
 
@@ -363,19 +394,3 @@ pub(crate) fn verify_signature_body(
 
     Ok(())
 }
-
-/// Verify the signature of a JWT, and return a header object and raw payload.
-///
-/// If the token or its signature is invalid, it will return an error.
-fn verify_signature<'a>(
-    token: &'a [u8],
-    validation: &Validation,
-    verifying_provider: Box<dyn JwtVerifier>,
-) -> Result<(Header, &'a [u8])> {
-    let (signature, message) = expect_two!(token.rsplitn(2, |b| *b == b'.'));
-    let (payload, header) = expect_two!(message.rsplitn(2, |b| *b == b'.'));
-    let header = Header::from_encoded(header)?;
-    verify_signature_body(message, signature, &header, validation, verifying_provider)?;
-
-    Ok((header, payload))
-}

src/encoding.rs

@@ -10,7 +10,7 @@ use crate::Algorithm;
 use crate::algorithms::AlgorithmFamily;
 use crate::crypto::JwtSigner;
 use crate::errors::{ErrorKind, Result, new_error};
-use crate::header::Header;
+use crate::header::Alg;
 #[cfg(feature = "use_pem")]
 use crate::pem::decoder::PemEncodedKey;
 use crate::serialization::{b64_encode, b64_encode_part};
@@ -171,14 +171,18 @@ impl Debug for EncodingKey {
 /// // This will create a JWT using HS256 as algorithm
 /// let token = encode(&Header::default(), &my_claims, &EncodingKey::from_secret("secret".as_ref())).unwrap();
 /// ```
-pub fn encode<T: Serialize>(header: &Header, claims: &T, key: &EncodingKey) -> Result<String> {
-    if key.family != header.alg.family() {
+pub fn encode<H: Serialize + Alg, T: Serialize>(
+    header: &H,
+    claims: &T,
+    key: &EncodingKey,
+) -> Result<String> {
+    if key.family != header.alg().family() {
         return Err(new_error(ErrorKind::InvalidAlgorithm));
     }
 
-    let signing_provider = jwt_signer_factory(&header.alg, key)?;
+    let signing_provider = jwt_signer_factory(header.alg(), key)?;
 
-    if signing_provider.algorithm() != header.alg {
+    if signing_provider.algorithm() != *header.alg() {
         return Err(new_error(ErrorKind::InvalidAlgorithm));
     }
 

src/header.rs

@@ -1,3 +1,4 @@
+//! Traits and datastructures for JWT Headers
 use std::collections::HashMap;
 use std::result;
 
@@ -25,12 +26,19 @@ const ENC_A256GCM: &str = "A256GCM";
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 #[allow(clippy::upper_case_acronyms, non_camel_case_types)]
 pub enum Enc {
+    /// HMAC-256
     A128CBC_HS256,
+    /// HMAC-384
     A192CBC_HS384,
+    /// HMAC-512
     A256CBC_HS512,
+    /// AES-GCM 128
     A128GCM,
+    /// AES-GCM 192
     A192GCM,
+    /// AES-GCM 256
     A256GCM,
+    /// Other encryption type
     Other(String),
 }
 
@@ -76,7 +84,9 @@ impl<'de> Deserialize<'de> for Enc {
 /// Defined in [RFC7516#4.1.3](https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.3).
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Zip {
+    /// Basic Deflate Compression
     Deflate,
+    /// Other Compression
     Other(String),
 }
 
@@ -106,6 +116,25 @@ impl<'de> Deserialize<'de> for Zip {
     }
 }
 
+/// Getter for `alg` attribute of a JWT Header
+/// This must be implemented by custom header structs
+pub trait Alg {
+    /// Getter for `alg`
+    fn alg(&self) -> &Algorithm;
+}
+
+/// Decodes a JWT part from b64
+pub trait FromEncoded {
+    /// Converts an encoded JWT part into the Header struct if possible
+    fn from_encoded<T: AsRef<[u8]>>(encoded_part: T) -> Result<Self>
+    where
+        Self: Sized + serde::de::DeserializeOwned,
+    {
+        let decoded = b64_decode(encoded_part)?;
+        Ok(serde_json::from_slice(&decoded)?)
+    }
+}
+
 /// A basic JWT header, the alg defaults to HS256 and typ is automatically
 /// set to `JWT`. All the other fields are optional.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -213,12 +242,6 @@ impl Header {
         }
     }
 
-    /// Converts an encoded part into the Header struct if possible
-    pub(crate) fn from_encoded<T: AsRef<[u8]>>(encoded_part: T) -> Result<Self> {
-        let decoded = b64_decode(encoded_part)?;
-        Ok(serde_json::from_slice(&decoded)?)
-    }
-
     /// Decodes the X.509 certificate chain into ASN.1 DER format.
     pub fn x5c_der(&self) -> Result<Option<Vec<Vec<u8>>>> {
         Ok(self
@@ -237,3 +260,11 @@ impl Default for Header {
         Header::new(Algorithm::default())
     }
 }
+
+impl Alg for Header {
+    fn alg(&self) -> &Algorithm {
+        &self.alg
+    }
+}
+
+impl FromEncoded for Header {}

src/jws.rs

@@ -5,7 +5,10 @@ use crate::crypto::sign;
 use crate::errors::{ErrorKind, Result, new_error};
 use crate::serialization::{DecodedJwtPartClaims, b64_encode_part};
 use crate::validation::validate;
-use crate::{DecodingKey, EncodingKey, Header, TokenData, Validation};
+use crate::{
+    DecodingKey, EncodingKey, TokenData, Validation,
+    header::{FromEncoded, Header},
+};
 
 use crate::decoding::{jwt_verifier_factory, verify_signature_body};
 use serde::de::DeserializeOwned;
@@ -63,7 +66,7 @@ pub fn decode<T: DeserializeOwned>(
     jws: &Jws<T>,
     key: &DecodingKey,
     validation: &Validation,
-) -> Result<TokenData<T>> {
+) -> Result<TokenData<Header, T>> {
     let header = Header::from_encoded(&jws.protected)?;
     let message = [jws.protected.as_str(), jws.payload.as_str()].join(".");
 

src/lib.rs

@@ -12,7 +12,9 @@ compile_error!(
 compile_error!("at least one of the features \"rust_crypto\" or \"aws_lc_rs\" must be enabled");
 
 pub use algorithms::Algorithm;
-pub use decoding::{DecodingKey, TokenData, decode, decode_header};
+pub use decoding::{
+    DecodingKey, TokenData, decode, decode_custom_header, decode_header, decode_with_custom_header,
+};
 pub use encoding::{EncodingKey, encode};
 pub use header::Header;
 pub use validation::{Validation, get_current_timestamp};
@@ -24,7 +26,7 @@ mod decoding;
 mod encoding;
 /// All the errors that can be encountered while encoding/decoding JWTs
 pub mod errors;
-mod header;
+pub mod header;
 pub mod jwk;
 pub mod jws;
 #[cfg(feature = "use_pem")]

tests/header/mod.rs

@@ -1,7 +1,10 @@
 use base64::{Engine, engine::general_purpose::STANDARD};
 use wasm_bindgen_test::wasm_bindgen_test;
 
-use jsonwebtoken::Header;
+use jsonwebtoken::{
+    Algorithm,
+    header::{Alg, FromEncoded, Header},
+};
 
 static CERT_CHAIN: [&str; 3] = include!("cert_chain.json");
 
@@ -38,3 +41,31 @@ fn x5c_der_invalid_chain() {
 
     assert!(header.x5c_der().is_err());
 }
+
+#[test]
+#[wasm_bindgen_test]
+fn decode_custom_header() {
+    #[derive(Debug, PartialEq, Eq, Clone, serde::Deserialize)]
+    struct CustomHeader {
+        alg: Algorithm,
+        typ: String,
+        nonstandard_header: String,
+    }
+    impl Alg for CustomHeader {
+        fn alg(&self) -> &Algorithm {
+            &self.alg
+        }
+    }
+    impl FromEncoded for CustomHeader {}
+
+    let expected = CustomHeader {
+        alg: Algorithm::HS256,
+        typ: "JWT".into(),
+        nonstandard_header: "traits are awesome".into(),
+    };
+
+    let token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsIm5vbnN0YW5kYXJkX2hlYWRlciI6InRyYWl0cyBhcmUgYXdlc29tZSJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNzU5OTY4MTQ1fQ.c2VjcmV0";
+
+    let header = jsonwebtoken::decode_custom_header::<CustomHeader>(token).unwrap();
+    assert_eq!(header, expected);
+}