Struct ockam::Profile

pub struct Profile { /* fields omitted */ }

Profile is an abstraction responsible for keeping, verifying and modifying user’s data (mainly - public keys). It is used to create new keys, rotate and revoke them. Public keys together with metadata will be organised into events chain, corresponding secret keys will be saved into the given Vault implementation. Events chain and corresponding secret keys are what fully determines Profile.

Examples

Create a Profile. Add and rotate keys.

let vault = Arc::new(Mutex::new(SoftwareVault::default()));
let mut profile = Profile::create(None, vault)?;

let root_key_attributes = KeyAttributes::new(
    Profile::PROFILE_UPDATE.to_string(),
);

let _alice_root_secret = profile.get_secret_key(&root_key_attributes)?;

let truck_key_attributes = KeyAttributes::new(
    "Truck management".to_string(),
);

profile.create_key(truck_key_attributes.clone(), None)?;

let _alice_truck_secret = profile.get_secret_key(&truck_key_attributes)?;

profile.rotate_key(truck_key_attributes.clone(), None)?;

let _alice_truck_secret = profile.get_secret_key(&truck_key_attributes)?;

profile.verify()?;

Authentication using Profile. In following example Bob authenticates Alice.

fn alice_main() -> ockam_core::Result<()> {
    let vault = Arc::new(Mutex::new(SoftwareVault::default()));

    // Alice generates profile
    let alice = Profile::create(None, vault)?;

    // Key agreement happens here
    let key_agreement_hash = [0u8; 32];

    // Send this over the network to Bob
    let contact_alice = alice.serialize_to_contact()?;
    let proof_alice = alice.generate_authentication_proof(&key_agreement_hash)?;

    Ok(())
}

fn bob_main() -> ockam_core::Result<()> {
    let vault = Arc::new(Mutex::new(SoftwareVault::default()));

    // Bob generates profile
    let mut bob = Profile::create(None, vault)?;

    // Key agreement happens here
    let key_agreement_hash = [0u8; 32];

    // Receive this from Alice over the network
    let contact_alice = Profile::deserialize_contact(&contact_alice)?;
    let alice_id = contact_alice.identifier().clone();

    // Bob adds Alice to contact list
    bob.verify_and_add_contact(contact_alice)?;

    // Bob verifies Alice
    bob.verify_authentication_proof(&key_agreement_hash, &alice_id, &proof_alice)
}

Update Profile and send changes to other parties. In following example Alice rotates her key and sends corresponding Profile changes to Bob.

fn alice_main() -> ockam_core::Result<()> {
    let index_a = alice.change_events().len();
    alice.rotate_key(Profile::PROFILE_UPDATE.into(), None)?;

    // Send to Bob
    let change_events = &alice.change_events()[index_a..];
    let change_events = Profile::serialize_change_events(change_events)?;

    Ok(())
}

fn bob_main() -> ockam_core::Result<()> {
    // Receive from Alice
    let change_events = Profile::deserialize_change_events(&change_events)?;
    bob.verify_and_update_contact(&alice_id, change_events)
}

Implementations

impl Profile

pub const NO_EVENT: &'static [u8]

Sha256 of that value is used as previous event id for first event in a Profile

pub const PROFILE_UPDATE: &'static str

Label for Profile update key

pub const CREDENTIALS_ISSUE: &'static str

Label for key used to issue credentials

pub const CURRENT_CHANGE_VERSION: u8

Current version of change structure

impl Profile

pub fn identifier(&self) -> &ProfileIdentifier

Return unique Profile identifier, which is equal to sha256 of the root public key

pub fn change_events(&self) -> &[ProfileChangeEvent]

Return change history chain

pub fn contacts(&self) -> &ContactsDb

Return all known to this profile Contacts

impl Profile

pub fn new(
    identifier: ProfileIdentifier,
    change_events: Vec<ProfileChangeEvent>,
    contacts: ContactsDb,
    vault: Arc<Mutex<dyn ProfileVault>>
) -> Self

impl Profile

pub fn create(
    attributes: Option<ProfileEventAttributes>,
    vault: Arc<Mutex<dyn ProfileVault>>
) -> Result<Self>

Generate fresh Profile update key key and create new Profile using it

pub fn create_key(
    &mut self,
    key_attributes: KeyAttributes,
    attributes: Option<ProfileEventAttributes>
) -> Result<()>

Create new key. Key is uniquely identified by label in KeyAttributes

pub fn rotate_key(
    &mut self,
    key_attributes: KeyAttributes,
    attributes: Option<ProfileEventAttributes>
) -> Result<()>

Rotate existing key. Key is uniquely identified by label in KeyAttributes

pub fn get_secret_key(&self, key_attributes: &KeyAttributes) -> Result<Secret>

Get Secret key. Key is uniquely identified by label in KeyAttributes

pub fn get_public_key(
    &self,
    key_attributes: &KeyAttributes
) -> Result<PublicKey>

Get PublicKey. Key is uniquely identified by label in KeyAttributes

impl Profile

pub fn verify(&self) -> Result<()>

Verify whole event chain of current Profile

impl Profile

pub fn to_contact(&self) -> Contact

Convert Profile to Contact

pub fn serialize_to_contact(&self) -> Result<Vec<u8>>

Serialize Profile to Contact in binary form for storing/transferring over the network

pub fn serialize_contact(contact: &Contact) -> Result<Vec<u8>>

Serialize Contact in binary form for storing/transferring over the network

pub fn deserialize_contact(contact: &[u8]) -> Result<Contact>

Deserialize Contact from binary form

pub fn serialize_change_events(
    change_events: &[ProfileChangeEvent]
) -> Result<Vec<u8>>

Serialize ProfileChangeEvents to binary form for storing/transferring over the network

pub fn deserialize_change_events(
    change_events: &[u8]
) -> Result<Vec<ProfileChangeEvent>>

Deserialize ProfileChangeEvents from binary form

pub fn get_contact(&self, id: &ProfileIdentifier) -> Option<&Contact>

Return Contact with given ProfileIdentifier

pub fn verify_contact(&self, contact: &Contact) -> Result<()>

Verify cryptographically whole event chain. Also verify sequence correctness

pub fn verify_and_add_contact(&mut self, contact: Contact) -> Result<()>

Verify and add new Contact to Profile’s Contact list

pub fn verify_and_update_contact(
    &mut self,
    profile_id: &ProfileIdentifier,
    change_events: Vec<ProfileChangeEvent>
) -> Result<()>

Verify and update known Contact with new ProfileChangeEvents

impl Profile

pub fn generate_authentication_proof(
    &self,
    channel_state: &[u8]
) -> Result<Vec<u8>>

Generate Proof of possession of Profile. channel_state should be tied to channel’s cryptographical material (e.g. h value for Noise XX)

pub fn verify_authentication_proof(
    &self,
    channel_state: &[u8],
    responder_contact_id: &ProfileIdentifier,
    proof: &[u8]
) -> Result<()>

Verify Proof of possession of Profile with given ProfileIdentifier. channel_state should be tied to channel’s cryptographical material (e.g. h value for Noise XX)

Trait Implementations

impl Clone for Profile

fn clone(&self) -> Profile

Returns a copy of the value.

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

Performs copy-assignment from source.