Trait secret_keeper::keepers::SecretKeeper

pub trait SecretKeeper: Debug + Sync + Send {
#[must_use]    fn wrap<'life0, 'life1, 'life2, 'life3, 'async_trait>(
        &'life0 self, 
        uri: &'life1 str, 
        nonce: &'life2 [u8], 
        key: &'life3 [u8]
    ) -> Pin<Box<dyn Future<Output = Result<WrappedKey, Error>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        'life3: 'async_trait,
        Self: 'async_trait;
#[must_use]    fn unwrap<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self, 
        nonce: &'life1 [u8], 
        wk: &'life2 WrappedKey
    ) -> Pin<Box<dyn Future<Output = Result<Bytes, Error>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        Self: 'async_trait;
    fn get_scheme(&self) -> &str;

#[must_use]    fn init_cipher<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self, 
        ckind: CipherKind, 
        nonce: &'life1 [u8], 
        wrapped: Option<&'life2 WrappedKey>
    ) -> Pin<Box<dyn Future<Output = Result<Box<dyn Cipher>, Error>> + Send + 'async_trait>>
    where
        'life0: 'async_trait,
        'life1: 'async_trait,
        'life2: 'async_trait,
        Self: 'async_trait,
    { ... }
    fn as_create(&self) -> Result<&dyn Create, Error> { ... }
}

SecretKeeper encrypts and decrypts data-encryption keys

Required methods

#[must_use]fn wrap<'life0, 'life1, 'life2, 'life3, 'async_trait>(
    &'life0 self,
    uri: &'life1 str,
    nonce: &'life2 [u8],
    key: &'life3 [u8]
) -> Pin<Box<dyn Future<Output = Result<WrappedKey, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    'life3: 'async_trait,
    Self: 'async_trait, 

Encrypts key and packages in a format that can be transmitted or stored on disk. Applications should use Cipher::export to encrypt and wrap data encryption keys, instead of calling this function. This function is called by ciphers from Cipher::export.

The nonce parameter is used by some SecretKeepers during the key encryption process. After encryption, the Key is stringified with bech32.

#[must_use]fn unwrap<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    nonce: &'life1 [u8],
    wk: &'life2 WrappedKey
) -> Pin<Box<dyn Future<Output = Result<Bytes, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Unwraps and decrypts data-encryption key. Applications should use init_cipher to unwrap a key and create a cipher, rather than calling this function directly.

fn get_scheme(&self) -> &str

Returns uri scheme for this keeper

Loading content...

Provided methods

#[must_use]fn init_cipher<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    ckind: CipherKind,
    nonce: &'life1 [u8],
    wrapped: Option<&'life2 WrappedKey>
) -> Pin<Box<dyn Future<Output = Result<Box<dyn Cipher>, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Initialize a new encryption cipher.

If wrappedKey has a value, it is decrypted by the SecretKeeper, and the resulting key is used to initialize the cipher. If wrappedKey is None, the cipher is initalized with a new key generated by the platform's CSRNG.

nonce: A nonce that will initialize the content cipher and also may be used by some keepers (including 'env' and 'prompt') to initialize the keeper's cipher for key encryption. TL;DR: nonce should be 24 random bytes; you can use secret_keeper::rand to initialize it.

In more detail, for env and prompt keepers, the nonce parameter must be at least 24 bytes, even if the cipher is AES_GCM_256, which uses a 12 byte nonce, because the 24-byte nonce is used for encrypting and decrypting the key using xchacha20-poly1305 in the envelope. If AesGcm256 is the chosen CipherKind, the first 12 bytes of the nonce parameter will be used to initialize the AesGcm256 cipher. For other keepers (hashivault, cloudkms, etc.) that encrypt keys with an external service, the nonce length can be whatever NONCEBYTES is required by the desired cipher. For the most flexible code, 24 bytes always is recommended.

fn as_create(&self) -> Result<&dyn Create, Error>

attempts to cast keeper to Create. Returns Error if create() is not implemented.

Loading content...

Implementations

impl dyn SecretKeeper

pub async fn for_uri<'_>(uri: &'_ str) -> Result<Arc<Box<Self>>, Error>

Find keeper for uri

pub async fn register(keeper: Box<dyn SecretKeeper>) -> Result<(), Error>

Register a keeper. This only fails if uri scheme is missing or not lowercase

Implementors

impl SecretKeeper for EnvKeeper

fn get_scheme(&self) -> &str

returns the uri scheme

fn wrap<'life0, 'life1, 'life2, 'life3, 'async_trait>(
    &'life0 self,
    uri: &'life1 str,
    nonce: &'life2 [u8],
    key: &'life3 [u8]
) -> Pin<Box<dyn Future<Output = Result<WrappedKey, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    'life3: 'async_trait,
    Self: 'async_trait, 

Encrypts key with a passphrase-generated key Passphrase is retrieved from enviornment variable (default VAULT_PASSWORD, or the name in the key uri "env:<VAR_NAME>"). Returned encrypted key is stringified with bech32. Applications using envelope encryption don't call this function directly, but instead use Cipher.export. Cipher.export invokes SecretKeeper.wrap to encrypt the key and generate the WrappedKey.

fn unwrap<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 self,
    nonce: &'life1 [u8],
    wk: &'life2 WrappedKey
) -> Pin<Box<dyn Future<Output = Result<Bytes, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    Self: 'async_trait, 

Unwraps and decrypts key with a passphrase-generated key Passphrase is retrieved from enviornment variable (default VAULT_PASSWORD, or the name in the key uri "env:<VAR_NAME>").

Loading content...