jsonwebtoken/
encoding.rs

Help
1use base64::{engine::general_purpose::STANDARD, Engine};
2use serde::ser::Serialize;
3
4use crate::algorithms::AlgorithmFamily;
5use crate::crypto;
6use crate::errors::{new_error, ErrorKind, Result};
7use crate::header::Header;
8#[cfg(feature = "use_pem")]
9use crate::pem::decoder::PemEncodedKey;
10use crate::serialization::b64_encode_part;
11
12/// A key to encode a JWT with. Can be a secret, a PEM-encoded key or a DER-encoded key.
13/// This key can be re-used so make sure you only initialize it once if you can for better performance.
14#[derive(Clone)]
15pub struct EncodingKey {
16    pub(crate) family: AlgorithmFamily,
17    content: Vec<u8>,
18}
19
20impl EncodingKey {
21    /// If you're using a HMAC secret that is not base64, use that.
22    pub fn from_secret(secret: &[u8]) -> Self {
23        EncodingKey { family: AlgorithmFamily::Hmac, content: secret.to_vec() }
24    }
25
26    /// If you have a base64 HMAC secret, use that.
27    pub fn from_base64_secret(secret: &str) -> Result<Self> {
28        let out = STANDARD.decode(secret)?;
29        Ok(EncodingKey { family: AlgorithmFamily::Hmac, content: out })
30    }
31
32    /// If you are loading a RSA key from a .pem file.
33    /// This errors if the key is not a valid RSA key.
34    /// Only exists if the feature `use_pem` is enabled.
35    ///
36    /// # NOTE
37    ///
38    /// According to the [ring doc](https://docs.rs/ring/latest/ring/signature/struct.RsaKeyPair.html#method.from_pkcs8),
39    /// the key should be at least 2047 bits.
40    ///
41    #[cfg(feature = "use_pem")]
42    pub fn from_rsa_pem(key: &[u8]) -> Result<Self> {
43        let pem_key = PemEncodedKey::new(key)?;
44        let content = pem_key.as_rsa_key()?;
45        Ok(EncodingKey { family: AlgorithmFamily::Rsa, content: content.to_vec() })
46    }
47
48    /// If you are loading a ECDSA key from a .pem file
49    /// This errors if the key is not a valid private EC key
50    /// Only exists if the feature `use_pem` is enabled.
51    ///
52    /// # NOTE
53    ///
54    /// The key should be in PKCS#8 form.
55    ///
56    /// You can generate a key with the following:
57    ///
58    /// ```sh
59    /// openssl ecparam -genkey -noout -name prime256v1 \
60    ///     | openssl pkcs8 -topk8 -nocrypt -out ec-private.pem
61    /// ```
62    #[cfg(feature = "use_pem")]
63    pub fn from_ec_pem(key: &[u8]) -> Result<Self> {
64        let pem_key = PemEncodedKey::new(key)?;
65        let content = pem_key.as_ec_private_key()?;
66        Ok(EncodingKey { family: AlgorithmFamily::Ec, content: content.to_vec() })
67    }
68
69    /// If you are loading a EdDSA key from a .pem file
70    /// This errors if the key is not a valid private Ed key
71    /// Only exists if the feature `use_pem` is enabled.
72    #[cfg(feature = "use_pem")]
73    pub fn from_ed_pem(key: &[u8]) -> Result<Self> {
74        let pem_key = PemEncodedKey::new(key)?;
75        let content = pem_key.as_ed_private_key()?;
76        Ok(EncodingKey { family: AlgorithmFamily::Ed, content: content.to_vec() })
77    }
78
79    /// If you know what you're doing and have the DER-encoded key, for RSA only
80    pub fn from_rsa_der(der: &[u8]) -> Self {
81        EncodingKey { family: AlgorithmFamily::Rsa, content: der.to_vec() }
82    }
83
84    /// If you know what you're doing and have the DER-encoded key, for ECDSA
85    pub fn from_ec_der(der: &[u8]) -> Self {
86        EncodingKey { family: AlgorithmFamily::Ec, content: der.to_vec() }
87    }
88
89    /// If you know what you're doing and have the DER-encoded key, for EdDSA
90    pub fn from_ed_der(der: &[u8]) -> Self {
91        EncodingKey { family: AlgorithmFamily::Ed, content: der.to_vec() }
92    }
93
94    pub(crate) fn inner(&self) -> &[u8] {
95        &self.content
96    }
97}
98
99/// Encode the header and claims given and sign the payload using the algorithm from the header and the key.
100/// If the algorithm given is RSA or EC, the key needs to be in the PEM format.
101///
102/// ```rust
103/// use serde::{Deserialize, Serialize};
104/// use jsonwebtoken::{encode, Algorithm, Header, EncodingKey};
105///
106/// #[derive(Debug, Serialize, Deserialize)]
107/// struct Claims {
108///    sub: String,
109///    company: String
110/// }
111///
112/// let my_claims = Claims {
113///     sub: "b@b.com".to_owned(),
114///     company: "ACME".to_owned()
115/// };
116///
117/// // my_claims is a struct that implements Serialize
118/// // This will create a JWT using HS256 as algorithm
119/// let token = encode(&Header::default(), &my_claims, &EncodingKey::from_secret("secret".as_ref())).unwrap();
120/// ```
121pub fn encode<T: Serialize>(header: &Header, claims: &T, key: &EncodingKey) -> Result<String> {
122    if key.family != header.alg.family() {
123        return Err(new_error(ErrorKind::InvalidAlgorithm));
124    }
125    let encoded_header = b64_encode_part(header)?;
126    let encoded_claims = b64_encode_part(claims)?;
127    let message = [encoded_header, encoded_claims].join(".");
128    let signature = crypto::sign(message.as_bytes(), key, header.alg)?;
129
130    Ok([message, signature].join("."))
131}
jsonwebtoken/encoding.rs

jsonwebtoken/
encoding.rs
