Crit, zip, enc, readme, refactor

Author: andrew

README.md

@@ -146,6 +146,20 @@ let token = decode::<Claims>(&token, &DecodingKey::from_rsa_components(jwk["n"],
 If your key is in PEM format, it is better performance wise to generate the `DecodingKey` once in a `lazy_static` or
 something similar and reuse it.
 
+### Encoding and decoding JWS
+
+JWS is handled the same way as JWT, but using `encode_jws` and `decode_jws`:
+
+```rust
+let encoded = encode_jws(&Header::default(), &my_claims, &EncodingKey::from_secret("secret".as_ref()))?;
+my_claims = decode_jws(&encoded, &DecodingKey::from_secret("secret".as_ref()), &Validation::default())?.claims;
+```
+
+`encode_jws` returns a `Jws<C>` struct which can be placed in other structs or serialized/deserialized from JSON directly.
+
+The generic parameter in `Jws<C>` indicates the claims type and prevents accidentally encoding or decoding the wrong claims type
+when the Jws is nested in another struct.
+
 ### Convert SEC1 private key to PKCS8
 `jsonwebtoken` currently only supports PKCS8 format for private EC keys. If your key has `BEGIN EC PRIVATE KEY` at the top,
 this is a SEC1 type and can be converted to PKCS8 like so:

src/decoding.rs

@@ -202,14 +202,13 @@ impl DecodingKey {
     }
 }
 
-/// Verify signature of a JWT, and return header object and raw payload
-///
-/// If the token or its signature is invalid, it will return an error.
-fn verify_signature<'a>(
-    token: &'a str,
+fn verify_signature_body(
+    header: &Header,
+    message: &str,
+    signature: &str,
     key: &DecodingKey,
     validation: &Validation,
-) -> Result<(Header, &'a str)> {
+) -> Result<()> {
     if validation.validate_signature && validation.algorithms.is_empty() {
         return Err(new_error(ErrorKind::MissingAlgorithm));
     }
@@ -222,10 +221,6 @@ fn verify_signature<'a>(
         }
     }
 
-    let (signature, message) = expect_two!(token.rsplitn(2, '.'));
-    let (payload, header) = expect_two!(message.rsplitn(2, '.'));
-    let header = Header::from_encoded(header)?;
-
     if validation.validate_signature && !validation.algorithms.contains(&header.alg) {
         return Err(new_error(ErrorKind::InvalidAlgorithm));
     }
@@ -234,6 +229,23 @@ fn verify_signature<'a>(
         return Err(new_error(ErrorKind::InvalidSignature));
     }
 
+    return Ok(());
+}
+
+/// Verify signature of a JWT, and return header object and raw payload
+///
+/// If the token or its signature is invalid, it will return an error.
+fn verify_signature<'a>(
+    token: &'a str,
+    key: &DecodingKey,
+    validation: &Validation,
+) -> Result<(Header, &'a str)> {
+    let (signature, message) = expect_two!(token.rsplitn(2, '.'));
+    let (payload, header) = expect_two!(message.rsplitn(2, '.'));
+    let header = Header::from_encoded(header)?;
+
+    verify_signature_body(&header, message, signature, key, validation)?;
+
     Ok((header, payload))
 }
 
@@ -296,31 +308,10 @@ fn verify_jws_signature<T>(
     key: &DecodingKey,
     validation: &Validation,
 ) -> Result<Header> {
-    if validation.validate_signature && validation.algorithms.is_empty() {
-        return Err(new_error(ErrorKind::MissingAlgorithm));
-    }
-
-    if validation.validate_signature {
-        for alg in &validation.algorithms {
-            if key.family != alg.family() {
-                return Err(new_error(ErrorKind::InvalidAlgorithm));
-            }
-        }
-    }
-
     let header = Header::from_encoded(&jws.protected)?;
-
-    if validation.validate_signature && !validation.algorithms.contains(&header.alg) {
-        return Err(new_error(ErrorKind::InvalidAlgorithm));
-    }
-
     let message = [jws.protected.as_str(), jws.payload.as_str()].join(".");
 
-    if validation.validate_signature
-        && !verify(&jws.signature, message.as_bytes(), key, header.alg)?
-    {
-        return Err(new_error(ErrorKind::InvalidSignature));
-    }
+    verify_signature_body(&header, &message, &jws.signature, key, validation)?;
 
     Ok(header)
 }

src/header.rs

@@ -1,13 +1,110 @@
 use std::result;
 
 use base64::{engine::general_purpose::STANDARD, Engine};
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
 use crate::algorithms::Algorithm;
 use crate::errors::Result;
 use crate::jwk::Jwk;
 use crate::serialization::b64_decode;
 
+const ZIP_SERIAL_DEFLATE: &'static str = "DEF";
+const ENC_A128CBC_HS256: &'static str = "A128CBC-HS256";
+const ENC_A192CBC_HS384: &'static str = "A192CBC-HS384";
+const ENC_A256CBC_HS512: &'static str = "A256CBC-HS512";
+const ENC_A128GCM: &'static str = "A128GCM";
+const ENC_A192GCM: &'static str = "A192GCM";
+const ENC_A256GCM: &'static str = "A256GCM";
+
+/// Encryption algorithm for encrypted payloads.
+///
+/// Defined in [RFC7516#4.1.2](https://datatracker.ietf.org/doc/html/rfc7516#section-4.1.2).
+///
+/// Values defined in [RFC7518#5.1](https://datatracker.ietf.org/doc/html/rfc7518#section-5.1).
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[allow(clippy::upper_case_acronyms)]
+pub enum Enc {
+    A128CBC_HS256,
+    A192CBC_HS384,
+    A256CBC_HS512,
+    A128GCM,
+    A192GCM,
+    A256GCM,
+    Other(String),
+}
+
+impl Serialize for Enc {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        match self {
+            Enc::A128CBC_HS256 => ENC_A128CBC_HS256,
+            Enc::A192CBC_HS384 => ENC_A192CBC_HS384,
+            Enc::A256CBC_HS512 => ENC_A256CBC_HS512,
+            Enc::A128GCM => ENC_A128GCM,
+            Enc::A192GCM => ENC_A192GCM,
+            Enc::A256GCM => ENC_A256GCM,
+            Enc::Other(v) => v,
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for Enc {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        match s.as_str() {
+            ENC_A128CBC_HS256 => return Ok(Enc::A128CBC_HS256),
+            ENC_A192CBC_HS384 => return Ok(Enc::A192CBC_HS384),
+            ENC_A256CBC_HS512 => return Ok(Enc::A256CBC_HS512),
+            ENC_A128GCM => return Ok(Enc::A128GCM),
+            ENC_A192GCM => return Ok(Enc::A192GCM),
+            ENC_A256GCM => return Ok(Enc::A256GCM),
+            _ => (),
+        }
+        Ok(Enc::Other(s))
+    }
+}
+/// Compression applied to plaintext.
+///
+/// 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 {
+    Deflate,
+    Other(String),
+}
+
+impl Serialize for Zip {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        match self {
+            Zip::Deflate => ZIP_SERIAL_DEFLATE,
+            Zip::Other(v) => v,
+        }
+        .serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for Zip {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        match s.as_str() {
+            ZIP_SERIAL_DEFLATE => return Ok(Zip::Deflate),
+            _ => (),
+        }
+        Ok(Zip::Other(s))
+    }
+}
+
 /// 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, Hash)]
@@ -64,6 +161,17 @@ pub struct Header {
     #[serde(skip_serializing_if = "Option::is_none")]
     #[serde(rename = "x5t#S256")]
     pub x5t_s256: Option<String>,
+    /// Critical - indicates header fields that must be understood by the receiver.
+    ///
+    /// Defined in [RFC7515#4.1.6](https://tools.ietf.org/html/rfc7515#section-4.1.6).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub crit: Option<Vec<String>>,
+    /// See `Enc` for description.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub enc: Option<Enc>,
+    /// See `Zip` for description.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub zip: Option<Zip>,
     /// ACME: The URL to which this JWS object is directed
     ///
     /// Defined in [RFC8555#6.4](https://datatracker.ietf.org/doc/html/rfc8555#section-6.4).
@@ -90,6 +198,9 @@ impl Header {
             x5c: None,
             x5t: None,
             x5t_s256: None,
+            crit: None,
+            enc: None,
+            zip: None,
             url: None,
             nonce: None,
         }