ockam_vault 0.132.0

A software-only Ockam Vault implementation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

use crate::{
    AeadSecretKeyHandle, HashOutput, HkdfOutput, SecretBufferHandle, X25519PublicKey,
    X25519SecretKeyHandle,
};

use ockam_core::compat::vec::Vec;
use ockam_core::{async_trait, compat::boxed::Box, Result};

/// Possible number of outputs of HKDF.
pub enum HKDFNumberOfOutputs {
    /// Derive 2 secrets.
    Two,
    /// Derive 3 secrets.
    Three,
}

/// Vault for running a Secure Channel
#[async_trait]
pub trait VaultForSecureChannels: Send + Sync + 'static {
    /// Perform X25519 ECDH.
    /// [1]: http://www.noiseprotocol.org/noise.html#dh-functions
    async fn x25519_ecdh(
        &self,
        secret_key_handle: &X25519SecretKeyHandle,
        peer_public_key: &X25519PublicKey,
    ) -> Result<SecretBufferHandle>;

    /// Compute Hash.
    /// [1]: http://www.noiseprotocol.org/noise.html#hash-functions
    async fn hash(&self, data: &[u8]) -> Result<HashOutput>;

    /// Compute HKDF.
    /// [1]: http://www.noiseprotocol.org/noise.html#hash-functions
    async fn hkdf(
        &self,
        salt: &SecretBufferHandle,
        input_key_material: Option<&SecretBufferHandle>,
        number_of_outputs: HKDFNumberOfOutputs,
    ) -> Result<HkdfOutput>;

    /// Perform AEAD encryption.
    /// [1]: http://www.noiseprotocol.org/noise.html#cipher-functions
    async fn aead_encrypt(
        &self,
        secret_key_handle: &AeadSecretKeyHandle,
        plain_text: &mut [u8],
        nonce: &[u8],
        aad: &[u8],
    ) -> Result<()>;

    /// Perform AEAD decryption.
    /// [1]: http://www.noiseprotocol.org/noise.html#cipher-functions
    async fn aead_decrypt<'a>(
        &self,
        secret_key_handle: &AeadSecretKeyHandle,
        cipher_text: &'a mut [u8],
        nonce: &[u8],
        aad: &[u8],
    ) -> Result<&'a mut [u8]>;

    /// Persist an existing AEAD key.
    async fn persist_aead_key(&self, secret_key_handle: &AeadSecretKeyHandle) -> Result<()>;

    /// Load an AEAD key from the storage.
    async fn load_aead_key(&self, secret_key_handle: &AeadSecretKeyHandle) -> Result<()>;

    /// Generate a fresh static (persisted) X25519 Key.
    async fn generate_static_x25519_secret_key(&self) -> Result<X25519SecretKeyHandle>;

    /// Delete static X25519 Key.
    async fn delete_static_x25519_secret_key(
        &self,
        secret_key_handle: X25519SecretKeyHandle,
    ) -> Result<bool>;

    /// Generate a fresh ephemeral (not persisted) X25519 Key.
    async fn generate_ephemeral_x25519_secret_key(&self) -> Result<X25519SecretKeyHandle>;

    /// Delete ephemeral X25519 Key.
    async fn delete_ephemeral_x25519_secret_key(
        &self,
        secret_key_handle: X25519SecretKeyHandle,
    ) -> Result<bool>;

    /// Get [`X25519PublicKey`] of the corresponding X25519 Secret Key given its Handle.
    async fn get_x25519_public_key(
        &self,
        secret_key_handle: &X25519SecretKeyHandle,
    ) -> Result<X25519PublicKey>;

    /// Get Handle to a X25519 Secret Key given its [`X25519PublicKey`].
    async fn get_x25519_secret_key_handle(
        &self,
        public_key: &X25519PublicKey,
    ) -> Result<X25519SecretKeyHandle>;

    /// Import a Secret Buffer.
    async fn import_secret_buffer(&self, buffer: Vec<u8>) -> Result<SecretBufferHandle>;

    /// Delete Secret Buffer.
    async fn delete_secret_buffer(&self, secret_buffer_handle: SecretBufferHandle) -> Result<bool>;

    /// Convert a Secret Buffer to an AEAD Key.
    async fn convert_secret_buffer_to_aead_key(
        &self,
        secret_buffer_handle: SecretBufferHandle,
    ) -> Result<AeadSecretKeyHandle>;

    /// Delete AEAD Key.
    async fn delete_aead_secret_key(&self, secret_key_handle: AeadSecretKeyHandle) -> Result<bool>;
}