ockam_identity 0.134.0

Ockam is a library for building devices that communicate securely, privately and trustfully with cloud services and other devices.
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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

use ockam_core::compat::sync::Arc;
use ockam_core::Result;
use ockam_vault::{SigningSecretKeyHandle, VaultForSigning, VaultForVerifyingSignatures};

use crate::identities::identities_verification::IdentitiesVerification;
use crate::identities::identity_builder::IdentityBuilder;
use crate::models::Identifier;
use crate::IdentityOptions;
use crate::{ChangeHistoryRepository, IdentitiesKeys, Identity, IdentityError};

/// This struct supports functions for the creation and import of identities using an IdentityVault
pub struct IdentitiesCreation {
    pub(super) repository: Arc<dyn ChangeHistoryRepository>,
    pub(super) identity_vault: Arc<dyn VaultForSigning>,
    pub(super) verifying_vault: Arc<dyn VaultForVerifyingSignatures>,
}

impl IdentitiesCreation {
    /// Create a new identities import module
    pub fn new(
        repository: Arc<dyn ChangeHistoryRepository>,
        identity_vault: Arc<dyn VaultForSigning>,
        verifying_vault: Arc<dyn VaultForVerifyingSignatures>,
    ) -> Self {
        Self {
            repository,
            identity_vault,
            verifying_vault,
        }
    }

    /// Return identities verification service
    pub fn identities_verification(&self) -> Arc<IdentitiesVerification> {
        Arc::new(IdentitiesVerification::new(
            self.repository.clone(),
            self.verifying_vault.clone(),
        ))
    }

    /// Return the identities keys management service
    pub fn identities_keys(&self) -> Arc<IdentitiesKeys> {
        Arc::new(IdentitiesKeys::new(
            self.identity_vault.clone(),
            self.verifying_vault.clone(),
        ))
    }

    /// Get an instance of [`IdentityBuilder`]
    pub fn identity_builder(&self) -> IdentityBuilder {
        IdentityBuilder::new(Arc::new(Self::new(
            self.repository.clone(),
            self.identity_vault.clone(),
            self.verifying_vault.clone(),
        )))
    }

    /// Create an `Identity` and store it
    pub async fn create_identity(&self) -> Result<Identifier> {
        let builder = self.identity_builder();
        builder.build().await
    }

    /// Create an `Identity` and store it
    pub async fn create_identity_with_options(
        &self,
        options: IdentityOptions,
    ) -> Result<Identifier> {
        let identity = self.identities_keys().create_initial_key(options).await?;
        self.repository
            .store_change_history(identity.identifier(), identity.change_history().clone())
            .await?;
        Ok(identity.identifier().clone())
    }

    /// Rotate an existing `Identity` and update the stored version
    pub async fn rotate_identity(&self, identifier: &Identifier) -> Result<()> {
        let builder = self.identity_builder();
        let options = builder.build_options().await?;

        self.rotate_identity_with_options(identifier, options).await
    }

    /// Rotate an existing `Identity` and update the stored version
    pub async fn rotate_identity_with_options(
        &self,
        identifier: &Identifier,
        options: IdentityOptions,
    ) -> Result<()> {
        let identity = self
            .identities_verification()
            .get_identity(identifier)
            .await?;
        let identity = self
            .identities_keys()
            .rotate_key_with_options(identity, options)
            .await?;

        self.identities_verification()
            .update_identity(&identity)
            .await?;

        Ok(())
    }

    /// Import an existing Identity from its binary format
    /// Its secret is expected to exist in the Vault (either generated there, or some Vault
    /// implementations may allow importing a secret)
    pub async fn import_private_identity(
        &self,
        expected_identifier: Option<&Identifier>,
        identity_change_history: &[u8],
        signing_secret_key_handle: &SigningSecretKeyHandle,
    ) -> Result<Identifier> {
        let identity = Identity::import(
            expected_identifier,
            identity_change_history,
            self.verifying_vault.clone(),
        )
        .await?;

        self.identities_verification()
            .update_identity(&identity)
            .await?;

        if identity.get_latest_public_key()?
            != self
                .identity_vault
                .get_verifying_public_key(signing_secret_key_handle)
                .await?
        {
            return Err(IdentityError::WrongSecretKey)?;
        }
        Ok(identity.identifier().clone())
    }

    /// [`SigningVault`]
    pub fn identity_vault(&self) -> Arc<dyn VaultForSigning> {
        self.identity_vault.clone()
    }

    /// [`VerifyingVault`]
    pub fn verifying_vault(&self) -> Arc<dyn VaultForVerifyingSignatures> {
        self.verifying_vault.clone()
    }
}