Tanker Core's security is based on the separation of knowledge, between the Tanker server, the user, and the application server. To establish trust between these actors and to enable sharing of encrypted data between users, Tanker Core produces and uses cryptographic keys, IDs, and tokens. The following section describes these elements, how they are generated, used, and, when applicable, stored.
It should be noted that they are only valid within a single Trustchain.
For a glossary of global terms used in this spec, please see the relevant section.
Here's a list of concepts used in the rest of this document:
- Tanker App
- An application created using Tanker's App management API
- Trustchain
- A Trustchain is a collection of signed blocks, attached to a given app
- User ID (UID)
- Unique identifier of a user
- Group ID (GID)
- Unique identifier of a group
- Device ID (DID)
- Unique identifier of a device belonging to a user
- User Secret (US)
- A secret generated and stored on the application server that protects the local encrypted storage
- Device Encryption Key Pair (DEK)
- Used to encrypt the user keys
- Device Signature Key Pair (DSK)
- Used when the user signs a block - like the addition of a new device
- Group Encryption Key Pair (GEK)
- Used when sharing data securely within a group
- Group Signature Key Pair (GSK)
- Used when the user modifies a group - like adding a new member to it
- Local Encrypted Storage (LES)
- A place where key materials are stored, encrypted at rest while the Tanker session is closed
- Resource Encryption Key (REK)
- A symmetric key that can be exchanged securely across users
- Shared Encrypted Key (SEK)
- The result of encrypting a Resource Encryption Key for a recipient
- Trustchain Signature Key Pair (TSK)
- Root of the Trustchain - used to sign user additions
- User Encryption Key Pair (UEK)
- Used for sharing encrypted keys across users. It is rotated when a device is revoked
- Verification Key (VFK)
- An opaque token that allows creating new devices
- Secret Permanent Identity (SPerID)
- An opaque string containing private data about user's identity
- Public Permanent Identity (PPerID)
- Generated from a Secret Permanent Identity - essentialy equivalent to a user ID
- Secret Provisional Identity (SProID)
- Same as Secret Permanent Identity, but for a user not registered on the Trustchain yet
- Public Provisional Identity (PProID)
- Same as Public Permanent Identity, but for a user not registered on the Trustchain yet
- Resource ID
- The unique ID of an encrypted data
- Verification Method
- Allows a *user* to retrieve their verification key. Used during Device or User registration
They are explained in more detail below.
An app is created using the App management API and managed by its creator. Creating an app gives a app secret and an app ID.
A Trustchain is an append-only cryptographic log of chained and signed blocks similar to a Blockchain (because all blocks are signed by Tanker Core and linked together). It is operated by a Trustchain server and responsible for storing and distributing blocks containing cryptographic materials required by Tanker Core to work. It is the source of truth for the public keys of all devices, users, and user groups. Tanker Core pushes and pulls blocks from the Trustchain.
A Trustchain is identified by a unique ID, a name, and a Trustchain Signature Key Pair. The name is informative only.
The Trustchain Signature Key Pair is generated client-side by the customer during the Trustchain creation. The Private Signature Key is called app secret in the App management API.
As such, it is only known by the customer and cannot be recovered by Tanker in any way - except if the "test mode" is enabled.
The public part of the Trustchain Signature Key Pair is included in the Trustchain's root block. The Trustchain ID is actually the hash of the Trustchain root block and is named app ID in the App management API.
The User ID identifies a user on the Trustchain. It is provided by the application when the user is created, and is part of the user's Secret Permanent Identity. Tanker Core cryptographically hashes User IDs locally before sending them to the Tanker server.
The Tanker session must be opened for the Local Encrypted Storage to be accessible. Once it is closed, no other program running on the device can access it.
The User Secret is a symmetric key, randomly generated by the application server for each user. It is part of the Secret Permanent Identity, and is considered an implementation detail not exposed by the Tanker API. A user secret cannot be changed once the user's first device has been created. It is used to encrypt and decrypt the Local Encrypted Storage and the Verification Key stored by the identity verification service.
A delegation token is a proof of the user's authentication with the application server. It is generated when the user opens their first session with Tanker Core.
The delegation token is composed of an ephemeral signature key pair, a delegation signature, and the User ID.
The delegation signature is created by combining the ephemeral public key and the User ID, then signing the result with the private Trustchain Signature Key Pair.
The delegation token is only used when the user creates their first device on the Trustchain, to sign the first device_creation block of that user.
The Secret Permanent Identity is generated and stored by the application server and provided to a user only after successful authentication against the application server. It should never be shared with other users. It contains some secret key material such as the User Secret and delegation token. It represents the identity of the user for Tanker Core and is considered a proof of authentication against the application server.
A Public Permanent Identity can be generated from a Secret Permanent Identity, and is used to uniquely identify a user. It contains a User ID, but no secret key material and it is safe to share publicly.
Each user must have at least one device. Devices are identified in Tanker Core by a randomly attributed Device ID. Each device has a Local Encrypted Storage.
Each device registered on the Trustchain has one Device Encryption Key Pair and one Device Signature Key Pair.
Device keys are stored in the device's Local Encrypted Storage. They are never replaced or modified after creation. The public Device Encryption Key Pair and Device Signature Key Pair are pushed to the Trustchain in the device_creation block. The private Device Encryption Key Pair and Device Signature Key Pair never leave the device.
Every user registered on the Trustchain has one active User Encryption Key Pair. User keys are stored in each device's Local Encrypted Storage. The Private User Encryption Key Pair is encrypted with each of the user's devices' public Device Encryption Key Pair before being pushed to the Trustchain. It is pushed to the Trustchain in the device_creation block and updated whenever a device is revoked.
A user group has one Group Encryption Key Pair and one Group Signature Key Pair. User group keys are stored in the device's Local Encrypted Storage. The private Group Signature Key Pair is encrypted with the private Group Encryption Key Pair, which is encrypted with each group member's User Encryption Key Pair. They are pushed to the Trustchain in the user_group_creation block and updated whenever a group member is removed from a user group. The group ID is the first public signature key of the group.
A new Resource Encryption Key is randomly generated each time a user encrypts data. The data is symmetrically encrypted with the Resource Encryption Key. The Resource Encryption Key can be encrypted for users or user groups. When sharing a resource key with a user, the Resource Encryption Key is encrypted using the User Encryption Key Pair of that user creating a Shared Encrypted Key. When sharing a resource key with a user group, the Resource Encryption Key is encrypted using the Group Encryption Key Pair of that user group creating a Shared Encrypted Key. Shared Encrypted Keys are pushed to the Trustchain in key_publish blocks. When received by a device, they are stored in the Local Encrypted Storage.
The Verification Key is used to register new devices in a secure manner. See the protocol documentation for more details.
A Verification Method is used to protect the encrypted Verification Key on the Tanker server. The user must provide a proof of their identity to access it. The user must establish this proof with the application and the Tanker server before being available to the user.
A Verification Code is a random 8 digits code communicated to a user without the application having access to the code. The Verification Code is used by a user to prove its identity to the Tanker server.
An OIDC Challenge is random and 24 bytes long. The OIDC Challenge is bound to a public key and only a signature from the key's secret counterpart can pass the challenge.
A Salt is used as an additional input to a hashing function. A different Salt is used for each input of the hashing function. The Salt protects relatively short data such as passphrase or phone numbers against attacks that use precomputed tables to guess the clear value of a hashed data.
A Secret Provisional Identity represents the identity of a user that is not yet registered on Tanker. It is split into two halves that are stored on the application server and on Tanker servers.
A provisional identity is attached to some authentication methods. For the moment, email and OpenID connect IDTokens are supported as well as phone numbers. Each half contains the name of the authentication method, a value (in case of email, the value is the email address), an encryption key pair, and a signature key pair.
A Public Provisional Identity can be generated from a Secret Provisional Identity and generally consists of the Secret Provisional Identity without its secrets parts. For the case of a Secret Provisional Identity that contains personally identifiable information (PII), such as an email address, the Public Provisional Identity contains a hashed value of this data.
Transport Layer Security is always used between Tanker Core and Tanker Server to exchange information. This guarantees the confidentiality and authenticity of the data exchanged.
The unique ID part of an encrypted data. This ID is used by Tanker core to associate encrypted data with their encryption key.
- application
- any application, web, desktop, or mobile, that uses Tanker Core to protect data for its users
- application server
- server supporting the application, responsible for the application's business logic, data storage, and user authentication
- block
- an atomic element of a Trustchain, signed by its device author and linked to other blocks
- customer
- Tanker's customer, the owner of the application, served to its users
- data
- any data (including files), owned by the user, stored by the customer to be used in the application
- device
- a web browser, mobile device, or computer on which the application runs
- group member
- a user being part of a user group
- Tanker
- provider of Tanker Core, the Trustchain, and the identity verification service
- Tanker Core
- a privacy SDK, integrated by the customer into the application, allowing to encrypt, decrypt, and share data between users
- Tanker server
- server hosting the Trustchain, and the identity verification service
- Trustchain
- a tamper-proof, append-only cryptographic log of chained and signed blocks
- virtual device
- a 'virtual' device associated with a user, it is the public part of an verification key registered on the Trustchain
- verification key
- a key stored either by the user or by the identity verification service to validate new device creations
- identity verification service
- an optional Tanker service involved in device management.
- user
- a user of the application, owning one or more devices
- user group
- a group of users, created and managed by the group members themselves. Data shared with a user group is accessible to all its group members
- resource
- same as data