Changes to support ACME, including JWS

From #359 and @andrewbaxter

Author: Keats

CHANGELOG.md

@@ -5,6 +5,7 @@
 - BREAKING: now using traits for crypto backends, you have to choose between `aws_lc_rs` and `rust_crypto`
 - Add `Clone` bound to `decode`
 - Support decoding byte slices
+- Support JWS
 
 ## 9.3.1 (2024-02-06)
 

README.md

@@ -111,6 +111,28 @@ RSA/EC, the key should always be the content of the private key in PEM or DER fo
 If your key is in PEM format, it is better performance wise to generate the `EncodingKey` 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.
+
+### JWK Thumbprints
+
+If you have a JWK object, you can generate a thumbprint like
+
+```
+let tp = my_jwk.thumbprint(&jsonwebtoken::DIGEST_SHA256);
+```
+
 ### Decoding
 
 ```rust

src/decoding.rs

@@ -332,14 +332,13 @@ pub fn decode_header(token: impl AsRef<[u8]>) -> Result<Header> {
     Header::from_encoded(header)
 }
 
-/// 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],
+pub(crate) fn verify_signature_body(
+    message: &[u8],
+    signature: &[u8],
+    header: &Header,
     validation: &Validation,
     verifying_provider: Box<dyn JwtVerifier>,
-) -> Result<(Header, &'a [u8])> {
+) -> Result<()> {
     if validation.validate_signature && validation.algorithms.is_empty() {
         return Err(new_error(ErrorKind::MissingAlgorithm));
     }
@@ -352,10 +351,6 @@ fn verify_signature<'a>(
         }
     }
 
-    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)?;
-
     if validation.validate_signature && !validation.algorithms.contains(&header.alg) {
         return Err(new_error(ErrorKind::InvalidAlgorithm));
     }
@@ -366,5 +361,21 @@ fn verify_signature<'a>(
         return Err(new_error(ErrorKind::InvalidSignature));
     }
 
+    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

@@ -1,6 +1,9 @@
 use std::fmt::{Debug, Formatter};
 
-use base64::{engine::general_purpose::STANDARD, Engine};
+use base64::{
+    engine::general_purpose::{STANDARD, URL_SAFE},
+    Engine,
+};
 use serde::ser::Serialize;
 
 use crate::algorithms::AlgorithmFamily;
@@ -36,7 +39,7 @@ use crate::crypto::rust_crypto::{
 #[derive(Clone)]
 pub struct EncodingKey {
     pub(crate) family: AlgorithmFamily,
-    content: Vec<u8>,
+    pub(crate) content: Vec<u8>,
 }
 
 impl EncodingKey {
@@ -56,6 +59,12 @@ impl EncodingKey {
         Ok(EncodingKey { family: AlgorithmFamily::Hmac, content: out })
     }
 
+    /// For loading websafe base64 HMAC secrets, ex: ACME EAB credentials.
+    pub fn from_urlsafe_base64_secret(secret: &str) -> Result<Self> {
+        let out = URL_SAFE.decode(secret)?;
+        Ok(EncodingKey { family: AlgorithmFamily::Hmac, content: out })
+    }
+
     /// If you are loading a RSA key from a .pem file.
     /// This errors if the key is not a valid RSA key.
     /// Only exists if the feature `use_pem` is enabled.

src/header.rs

@@ -2,13 +2,110 @@ use std::collections::HashMap;
 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: &str = "DEF";
+const ENC_A128CBC_HS256: &str = "A128CBC-HS256";
+const ENC_A192CBC_HS384: &str = "A192CBC-HS384";
+const ENC_A256CBC_HS512: &str = "A256CBC-HS512";
+const ENC_A128GCM: &str = "A128GCM";
+const ENC_A192GCM: &str = "A192GCM";
+const ENC_A256GCM: &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, non_camel_case_types)]
+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 => 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)]
@@ -65,7 +162,27 @@ 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).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub url: Option<String>,
+    /// ACME: Random data for preventing replay attacks.
+    ///
+    /// Defined in [RFC8555#6.5.2](https://datatracker.ietf.org/doc/html/rfc8555#section-6.5.2).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub nonce: Option<String>,
     /// Any additional non-standard headers not defined in [RFC7515#4.1](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1).
     /// Once serialized, all keys will be converted to fields at the root level of the header payload
     /// Ex: Dict("custom" -> "header") will be converted to "{"typ": "JWT", ..., "custom": "header"}"
@@ -87,6 +204,11 @@ impl Header {
             x5c: None,
             x5t: None,
             x5t_s256: None,
+            crit: None,
+            enc: None,
+            zip: None,
+            url: None,
+            nonce: None,
             extras: Default::default(),
         }
     }