Struct SymmetricKey

pub struct SymmetricKey(/* private fields */);

A symmetric encryption key used for both encryption and decryption.

SymmetricKey is a 32-byte cryptographic key used with ChaCha20-Poly1305 AEAD (Authenticated Encryption with Associated Data) encryption. This implementation follows the IETF ChaCha20-Poly1305 specification as defined in RFC-8439.

Symmetric encryption uses the same key for both encryption and decryption, unlike asymmetric encryption where different keys are used for each operation.

SymmetricKey can be used to encrypt plaintext into an EncryptedMessage that includes:

• Ciphertext (the encrypted data)
• Nonce (a unique number used once for each encryption)
• Authentication tag (to verify message integrity)
• Optional additional authenticated data (AAD)

Implementations

impl SymmetricKey

pub const SYMMETRIC_KEY_SIZE: usize = 32usize

pub fn new() -> Self

Create a new random symmetric key.

pub fn new_using(rng: &mut impl RandomNumberGenerator) -> Self

Create a new random symmetric key using the given random number generator.

pub const fn from_data(data: [u8; 32]) -> Self

Create a new symmetric key from data.

pub fn from_data_ref(data: impl AsRef<[u8]>) -> Result<Self>

Create a new symmetric key from data.

pub fn data(&self) -> &[u8; 32]

Get the data of the symmetric key.

pub fn from_hex(hex: impl AsRef<str>) -> Result<Self>

Create a new symmetric key from the given hexadecimal string.

Panics

Panics if the string is not exactly 24 hexadecimal digits.

pub fn hex(&self) -> String

The data as a hexadecimal string.

pub fn encrypt( &self, plaintext: impl Into<Vec<u8>>, aad: Option<impl Into<Vec<u8>>>, nonce: Option<impl AsRef<Nonce>>, ) -> EncryptedMessage

Encrypt the given plaintext with this key, and the given additional authenticated data and nonce.

pub fn encrypt_with_digest( &self, plaintext: impl Into<Vec<u8>>, digest: impl AsRef<Digest>, nonce: Option<impl AsRef<Nonce>>, ) -> EncryptedMessage

Encrypt the given plaintext with this key, and the given digest of the plaintext, and nonce.

pub fn decrypt(&self, message: &EncryptedMessage) -> Result<Vec<u8>>

Decrypt the given encrypted message with this key.

Trait Implementations

impl AsRef<SymmetricKey> for SymmetricKey

Implements AsRef<SymmetricKey> to allow self-reference.

fn as_ref(&self) -> &SymmetricKey

Converts this type into a shared reference of the (usually inferred) input type.

impl CBORTagged for SymmetricKey

Implements CBORTagged to provide the CBOR tag for the SymmetricKey.

fn cbor_tags() -> Vec<Tag>

Returns the CBOR tags associated with this type.

impl CBORTaggedDecodable for SymmetricKey

Implements CBORTaggedDecodable to provide CBOR decoding functionality.

fn from_untagged_cbor(cbor: CBOR) -> Result<Self>

Creates an instance of this type by decoding it from untagged CBOR.

fn from_tagged_cbor(cbor: CBOR) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from tagged CBOR.

fn from_tagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded tagged CBOR.

fn from_untagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded untagged CBOR.

impl CBORTaggedEncodable for SymmetricKey

Implements CBORTaggedEncodable to provide CBOR encoding functionality.

fn untagged_cbor(&self) -> CBOR

Returns the untagged CBOR encoding of this instance.

fn tagged_cbor(&self) -> CBOR

Returns the tagged CBOR encoding of this instance.

fn tagged_cbor_data(&self) -> Vec<u8>

Returns the tagged value in CBOR binary representation.

impl Clone for SymmetricKey

fn clone(&self) -> SymmetricKey

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SymmetricKey

Implements Debug formatting to display the key in hexadecimal format.

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

Formats the value using the given formatter.

impl Default for SymmetricKey

Implements Default to create a new random symmetric key.

fn default() -> Self

Returns the “default value” for a type.

impl<'a> From<&'a SymmetricKey> for &'a [u8; 32]

Implements conversion from a SymmetricKey reference to a byte array reference.

fn from(key: &'a SymmetricKey) -> Self

Converts to this type from the input type.

impl From<&SymmetricKey> for SymmetricKey

Implements conversion from a SymmetricKey reference to a SymmetricKey.

fn from(key: &SymmetricKey) -> Self

Converts to this type from the input type.

impl From<&SymmetricKey> for Vec<u8>

Implements conversion from a SymmetricKey reference to a Vec<u8>.

fn from(key: &SymmetricKey) -> Self

Converts to this type from the input type.

impl From<SymmetricKey> for CBOR

Implements conversion from SymmetricKey to CBOR for serialization.

fn from(value: SymmetricKey) -> Self

Converts to this type from the input type.

impl From<SymmetricKey> for Vec<u8>

Implements conversion from a SymmetricKey to a Vec<u8>.

fn from(key: SymmetricKey) -> Self

Converts to this type from the input type.

impl Hash for SymmetricKey

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for SymmetricKey

fn eq(&self, other: &SymmetricKey) -> 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 TryFrom<CBOR> for SymmetricKey

Implements TryFrom<CBOR> for SymmetricKey to support conversion from CBOR data.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl TryFrom<Vec<u8>> for SymmetricKey

Implements conversion from a Vec<u8> to a SymmetricKey.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: Vec<u8>) -> Result<Self, Self::Error>

Performs the conversion.

impl Eq for SymmetricKey

impl StructuralPartialEq for SymmetricKey