Enum JsonWebKey

#[non_exhaustive]
pub enum JsonWebKey<'a> {
    Rsa {
        modulus: Cow<'a, [u8]>,
        public_exponent: Cow<'a, [u8]>,
        private_parts: Option<RsaPrivateParts<'a>>,
    },
    EllipticCurve {
        curve: Cow<'a, str>,
        x: Cow<'a, [u8]>,
        y: Cow<'a, [u8]>,
        secret: Option<SecretBytes<'a>>,
    },
    Symmetric {
        secret: SecretBytes<'a>,
    },
    KeyPair {
        curve: Cow<'a, str>,
        x: Cow<'a, [u8]>,
        secret: Option<SecretBytes<'a>>,
    },
}

Basic JWK functionality: (de)serialization and creating thumbprints.

See RFC 7518 for the details about the fields for various key types.

Self::thumbprint() and the Display implementation allow to get the overall presentation of the key. The latter returns JSON serialization of the key with fields ordered alphabetically. That is, this output for verifying keys can be used to compute key thumbprints.

Serialization

For human-readable formats (e.g., JSON, TOML, YAML), byte fields in JsonWebKey and embedded types (SecretBytes, RsaPrivateParts, RsaPrimeFactor) will be serialized in base64-url encoding with no padding, as per the JWK spec. For other formats (e.g., CBOR), byte fields will be serialized as byte sequences.

Because of the limitations of the CBOR support in serde, a JsonWebKey serialized in CBOR is not compliant with the CBOR Object Signing and Encryption spec (COSE). It can still be a good way to decrease the serialized key size.

Conversions

A JWK can be obtained from signing and verifying keys defined in the alg module via From / Into traits. Conversion from a JWK to a specific key is fallible and can be performed via TryFrom with JwkError as an error type.

As a part of conversion for asymmetric signing keys, it is checked whether the signing and verifying parts of the JWK match; JwkError::MismatchedKeys is returned otherwise. This check is not performed for verifying keys even if the necessary data is present in the provided JWK.

⚠ Warning. Conversions for private RSA keys are not fully compliant with RFC 7518. See the docs for the relevant impls for more details.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Rsa

Public or private RSA key. Has kty field set to RSA.

Fields

modulus: Cow<'a, [u8]>

Key modulus (n).

public_exponent: Cow<'a, [u8]>

Public exponent (e).

private_parts: Option<RsaPrivateParts<'a>>

Private RSA parameters. Only present for private keys.

EllipticCurve

Public or private key in an ECDSA crypto system. Has kty field set to EC.

Fields

curve: Cow<'a, str>

Curve name (crv), such as secp256k1.

x: Cow<'a, [u8]>

x coordinate of the curve point.

y: Cow<'a, [u8]>

y coordinate of the curve point.

secret: Option<SecretBytes<'a>>

Secret scalar (d); not present for public keys.

Symmetric

Generic symmetric key, e.g. for HS256 algorithm. Has kty field set to oct.

Fields

secret: SecretBytes<'a>

Bytes representing this key.

KeyPair

Generic asymmetric keypair. This key type is used e.g. for Ed25519 keys.

Fields

curve: Cow<'a, str>

Curve name (crv), such as Ed25519.

x: Cow<'a, [u8]>

Public key. For Ed25519, this is the standard 32-byte public key presentation (x coordinate of a point on the curve + sign).

secret: Option<SecretBytes<'a>>

Secret key (d). For Ed25519, this is the seed.

Implementations

impl JsonWebKey<'_>

pub const fn key_type(&self) -> KeyType

Gets the type of this key.

pub const fn is_signing_key(&self) -> bool

Returns true if this key can be used for signing (has SecretBytes fields).

pub fn to_verifying_key(&self) -> JsonWebKey<'_>

Returns a copy of this key with parts not necessary for signature verification removed.

pub fn thumbprint<D>( &self, ) -> GenericArray<u8, <D as OutputSizeUser>::OutputSize>

where D: Digest,

Computes a thumbprint of this JWK. The result complies with the key thumbprint defined in RFC 7638.

Trait Implementations

impl<'a> Clone for JsonWebKey<'a>

fn clone(&self) -> JsonWebKey<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for JsonWebKey<'a>

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

Formats the value using the given formatter.

impl<'de, 'a> Deserialize<'de> for JsonWebKey<'a>

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for JsonWebKey<'_>

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

Formats the value using the given formatter.

impl<'a> From<&'a Hs256Key> for JsonWebKey<'a>

fn from(key: &'a Hs256Key) -> JsonWebKey<'a>

Converts to this type from the input type.

impl<'a> From<&'a Hs384Key> for JsonWebKey<'a>

fn from(key: &'a Hs384Key) -> JsonWebKey<'a>

Converts to this type from the input type.

impl<'a> From<&'a Hs512Key> for JsonWebKey<'a>

fn from(key: &'a Hs512Key) -> JsonWebKey<'a>

Converts to this type from the input type.

impl<'a> From<&'a SigningKey> for JsonWebKey<'a>

fn from(signing_key: &'a SigningKey) -> JsonWebKey<'a>

Converts to this type from the input type.

impl<'a> From<&'a VerifyingKey> for JsonWebKey<'a>

fn from(key: &'a VerifyingKey) -> JsonWebKey<'a>

Converts to this type from the input type.

impl<'a> PartialEq for JsonWebKey<'a>

fn eq(&self, other: &JsonWebKey<'a>) -> 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<'a> Serialize for JsonWebKey<'a>

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 TryFrom<&JsonWebKey<'_>> for Hs256Key

type Error = JwkError

The type returned in the event of a conversion error.

fn try_from( jwk: &JsonWebKey<'_>, ) -> Result<Hs256Key, <Hs256Key as TryFrom<&JsonWebKey<'_>>>::Error>

Performs the conversion.

impl TryFrom<&JsonWebKey<'_>> for Hs384Key

type Error = JwkError

The type returned in the event of a conversion error.

fn try_from( jwk: &JsonWebKey<'_>, ) -> Result<Hs384Key, <Hs384Key as TryFrom<&JsonWebKey<'_>>>::Error>

Performs the conversion.

impl TryFrom<&JsonWebKey<'_>> for Hs512Key

type Error = JwkError

The type returned in the event of a conversion error.

fn try_from( jwk: &JsonWebKey<'_>, ) -> Result<Hs512Key, <Hs512Key as TryFrom<&JsonWebKey<'_>>>::Error>

Performs the conversion.

impl<'a> StructuralPartialEq for JsonWebKey<'a>