Identities and Vaults

Ockam Identities are unique, cryptographically verifiable digital identities. These identities authenticate by proving possession of secret keys. Ockam Vaults safely store these secret keys.

In order to make decisions about trust, we must authenticate senders of messages.

Vaults

Ockam Identities authenticate by cryptographically proving possession of specific secret keys. Ockam Vaults safely store these secret keys in cryptographic hardware and cloud key management systems.

You can create a vault as follows:

» ockam vault create v1
     ✔︎ Vault created with name 'v1'!

This command will, by default, create a file system based vault, where your secret keys are stored at a specific file path.

Vaults are designed to be used in a way that secret keys never have to leave a vault. There is a growing base of Ockam Vault implementations in the Ockam GitHub Repository that safely store secret keys in specific KMSs, HSMs, Secure Enclaves etc.

Identities

Ockam Identities are unique, cryptographically verifiable digital identities.

You can create new identities, by typing:

» ockam identity create i1 --vault v1
     ✔︎ Identity Pef7f2a20c186b5adb03c0d7160879134135574663cc930d9b1cd664d63a45fb0
       created successfully as i1

The secret keys belonging to this identity are stored in the specified vault. This can be any type of vault - File Vault, AWS KMS, Azure KeyVault, YubiKey etc. If no vault is specified, the default vault is used. If a default vault doesn't exist yet, a new file systems based vault is created, set as default, and then used to generate secret keys.

To ensure privacy and eliminate the possibility of correlation of behavior across trust contexts, we've made it easy to generate and use different identities and identifiers for separate trust contexts.

Secret Keys

Each Ockam Identity starts its life by generating a secret key and its corresponding public key. Secret keys, must remain secret, while public keys can be shared with the world.

Ockam Identities support two types of Elliptic Curve secret keys that live in vaults - Curve25519 or NIST P-256.

Identifiers

Each Ockam Identity has a unique public identifier, called the Ockam Identifier of this identity:

» ockam identity show i1
I945b711058805c3e700e2f387d3f5458a0e0e62e806329154f70547fe12d0a78

This Identifier is generated by hashing the first public key of the Identity.

Change History

Ockam Identities can periodically rotate their keys to indicate that the latest public key is the one that should be used for authentication. Each Ockam Identity maintains a self-signed change history of key rotation events, you can see this full history by running:

» ockam identity show i1 --full
Identifier: I945b711058805c3e700e2f387d3f5458a0e0e62e806329154f70547fe12d0a78
  Change[0]:
    identifier:              945b711058805c3e700e2f387d3f5458a0e0e62e806329154f70547fe12d0a78
    primary_public_key:      EdDSACurve25519: db44d6e29006420b836fb2535c3c733711d3e05ef934aad16111596b7f4ede1a
    revoke_all_purpose_keys: false

Identifier Authentication

Authentication, within Ockam, starts by proving control of a specific Ockam Identifier. To prove control of a specific Identifier, the prover must present the identifier, the full signed change history of the identifier, and a signature on a challenge using the secret key corresponding to the latest public key in the identifier's change history.

If you're stuck or have questions at any point, please reach out to us.

Next, let's combine everything we've learnt so far to create mutually authenticated and end-to-end encrypted secure channels that guarantee data authenticity, integrity, and confidentiality.