Struct Key

Source

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

Expand description

A master key for the key derivation function

This key is used to derive multiple subkeys for different purposes. It must be exactly 32 bytes (256 bits) long and should be generated using a cryptographically secure random number generator.

§Security Properties

High entropy: Contains 256 bits of entropy when generated properly
Secret: Must be kept confidential to maintain security of all derived subkeys
Single source of truth: Allows multiple application-specific keys to be derived from a single master key

§Best Practices

Generate using the generate() method, which uses libsodium’s secure RNG
Store securely, preferably in a hardware security module or secure enclave
Rotate periodically according to your security policy
Consider using a key management service for production applications

§Example

use libsodium_rs as sodium;
use sodium::crypto_kdf;
use sodium::ensure_init;

// Initialize libsodium
ensure_init().expect("Failed to initialize libsodium");

// Generate a master key
let master_key = crypto_kdf::Key::generate().unwrap();

// Or create from existing bytes
let key_bytes = [0x42; crypto_kdf::KEYBYTES]; // Example bytes
let master_key = crypto_kdf::Key::from_slice(&key_bytes).unwrap();

Implementations§

Source §

impl Key

Source

pub fn generate() -> Result<Self>

Generates a new random key for key derivation

This function generates a new random master key suitable for deriving subkeys. The key is generated using libsodium’s secure random number generator.

§Example

use libsodium_rs as sodium;
use sodium::crypto_kdf;
use sodium::ensure_init;

// Initialize libsodium
ensure_init().expect("Failed to initialize libsodium");

// Generate a master key
let master_key = crypto_kdf::Key::generate().unwrap();

§Returns

Result<Self> - A new randomly generated key or an error

Source

pub fn from_slice(slice: &[u8]) -> Result<Self>

Creates a key from an existing byte slice

This function creates a master key from an existing byte slice. The slice must be exactly KEYBYTES (32) bytes long.

§Example

use libsodium_rs as sodium;
use sodium::crypto_kdf;
use sodium::ensure_init;

// Initialize libsodium
ensure_init().expect("Failed to initialize libsodium");

// Create a key from existing bytes
let key_bytes = [0x42; crypto_kdf::KEYBYTES]; // Example bytes
let master_key = crypto_kdf::Key::from_slice(&key_bytes).unwrap();

§Arguments

slice - Byte slice of exactly KEYBYTES length

§Returns

Result<Self> - A new key created from the slice or an error

§Errors

Returns an error if the slice is not exactly KEYBYTES bytes long

Source

pub fn as_bytes(&self) -> &[u8] ⓘ

Returns a reference to the key as a byte slice

This function returns a reference to the internal byte representation of the key. This is useful when you need to pass the key to other functions.

§Example

use libsodium_rs as sodium;
use sodium::crypto_kdf;
use sodium::ensure_init;

// Initialize libsodium
ensure_init().expect("Failed to initialize libsodium");

// Generate a master key
let master_key = crypto_kdf::Key::generate().unwrap();

// Get the bytes of the key
let key_bytes = master_key.as_bytes();
assert_eq!(key_bytes.len(), crypto_kdf::KEYBYTES);