Data Types & Functionality
EnvKey data types and properties that are relevant to cryptography or security, along with brief explanations of their functions.
User
{
firstName: String,
lastName: String,
email: String,
pubkey: Public Key,
encryptedPrivkey: Encrypted Private Key
}
An EnvKey user. A PGP keypair is generated on sign up (if creating a new org) or on acceptance of first invitation. A user can belong to multiple organizations.
The user's private key is encrypted with the master passphrase, then stored on the EnvKey server, which means the burden of supplying sufficient entropy to prevent brute force attacks is on the passphrase. The master passphrase is never sent to the server. Dropbox’s zxcvbn library is used to identify and block weak passphrases. See Tradeoffs for more discussion of this design.
OrgRole
"basic" | "org_admin" | "org_owner"
A basic user has their access level set on a per-app basis. An org admin acts as an app admin for every organization app, and can also create or delete apps and remove users from an organization. An org owner can manage billing and delete an org.
Invitation Idhash
sha256(JSON.stringify(
pubkeyFingerprint: Public Key Fingerprint,
org: {
id: UUID,
name: String
},
invitedBy: {
email: String,
pubkeyFingerprint: Public Key Fingerprint
},
invitee: {
email: String
}
}))
Acts as an invitation UUID, and also forms the first component of the Invitation Encryption Token, which is sent out of band from the inviting user to the invited user. Acts as a secure checksum that allows the invited user to verify invitation data from the server and the identity of the inviting user.
Invitation Encryption Token
d2d18c3b05e79e204913992714b9998ec2cd00849dd4d7dbf661ac8c6a39bc31_3KW9LzBMm8NVqDjr
Format is [Invitation Idhash]_[Invitation Passphrase]
This token is sent directly to the invited user by the inviter's chosen channel. The EnvKey server also sends an Invite Token to the invited user to verify their email address. Both tokens are required to accept an invitation, decrypt the invited user's config data, and then re-encrypt with the user's newly generated keypair after a master passphrase is set. This approach allows for secure, zero-knowledge invitations with only a minimum of inconvenience.
Invitation Idhash is generated client-side then stored on the server and used as both a lookup id and a client-side checksum that verifies the invitation server details that the server provides to the invitee.
Invitation Passphrase is a 16 character alphanumeric string. It is generated client-side and is never sent to the server.
Invitation
{
idhash: Invitation Idhash,
pubkey: Signed Public Key,
encryptedPrivateKey: Encrypted Private Key,
signedTrustedPubkeys: TrustChainShort
}
When inviting a new user, an invitation keypair is generated, and all config data the invited user is permitted to access is encrypted with that invitation keypair's public key (and signed by the inviting user). The invitation's public key is also signed by the inviting user. The inviting user's trusted public keys (see below) are also signed by the invitation's private key and stored alongside the invitation on the server. The invitation's private key is encrypted with the Invitation Passphrase portion of the Invite Encryption Token and also stored on the server.
OrgUser
{
userId: UUID,
orgId: UUID,
role: OrgRole,
signedPubkey: Signed Public Key,
signedTrustedPubkeys: TrustChainShort
}
Upon accepting an invitation, the user sets a master passphrase and generates a new PGP keypair. The new public key is signed by the Invitation's private key and stored on the OrgUser, creating a signature chain back to the inviting user (and eventually back to the organization owner). The invitation's trusted public key fingerprints, initially supplied and signed by the invitation's private key, are also now signed by the user's new private key and stored on the OrgUser, allowing the newly invited user to verify other public keys back to a trusted root public key.
Application
{
name: String
}
App User Role
"development" | "production" | "admin"
Environment
"development" | "staging" | "production" | "productionMetaOnly"
EnvsWithMetaCell
{
inherits: null | Environment,
val: String,
locked: Boolean,
hasVal: Boolean,
isEmpty: Boolean,
isUndefined: Boolean
}
Represents value for a particular config KEY and a particular Environment. Includes metadata describing inheritance and other info used by the EnvKey App ui.
EnvsWithMeta
{
development: {
KEY: EnvsWithMetaCell
},
staging: {
KEY: EnvsWithMetaCell
},
production: {
KEY: EnvsWithMetaCell
},
productionMetaOnly: {
KEY: EnvsWithMetaCell
}
}
Represents values for every config KEY and every Environment for an application along with associated metadata used by EnvKey App.
On update, encrypted copies are made on a per-Environment basis for each user that has access to the application and the Environment. Each copy is encrypted with the receiving user's public key and signed with the updating user's private key. On decryption, the signature is verified with the updating user's public key.
Before encrypting for any public key or verifying any signature, public keys are verified as trusted. If a public key's signature is not found directly in the user's list of trusted public key fingerprints for the organization, the EnvKey App attempts to verify the chain of signatures back to a fingerprint that is trusted.
RawEnv
{
KEY: "value",
KEY_2: "value2"
}
Represents a single environment's configuration as raw key value pairs in JSON. No metadata. These are encrypted for Servers and Local Development Keys, and are associated with an ENVKEY.
TrustedPubkeyFull
{
pubkey: Public Key,
invitePubkey: Public Key,
signedById: User UUID
}
Used in web of trust enforcement by the EnvKey Client Libraries. Verifies chain of public keys back to a trusted root without involvement of server. Stored in a TrustChain that is signed by/verified with a RawEnv's private key to prevent tampering.
TrustedPubkeyShort
{
pubkeyFingerpint: Public Key Fingerprint,
invitePubkeyFingerprint: Public Key Fingerprint,
invitedById: User UUID
}
Used in web of trust enforcement by the EnvKey App. Verifies user's public key, invite public key, and inviting user as supplied by the server. Stored in a TrustChainSort that is signed by/verified with user's private key to prevent tampering.
TrustChainFull
{
someUserId: TrustedPubkeyFull,
someServerId: TrustedPubkeyFull,
someLocalKeyId: TrustedPubkeyFull
}
Signature chain leading from organization owner to a generated RawEnv and associated ENVKEY. Contain full public keys so that the signature chain can be verified back to an initially trusted public key if needed. These are signed by the ENVKEY's associated private key and stored alongside the encrypted RawEnv so that EnvKey Client Libraries can verify the web of trust.
TrustChainShort
{
someUserId: TrustedPubkeyShort,
someServerId: TrustedPubkeyShort,
someLocalKeyId: TrustedPubkeyShort
}
Signature chain leading from organization owner to an Invitation or a user. Contain public key fingerprints. These are signed by the User's associated private key and stored on the OrgUser so that EnvKey App can verify the server's representation of the web of trust without trusting the server.
ENVKEY
ENVKEY=xZoF8tgxJGmHQ7nc9p7m-5c6XNw9YXz6yrxNa
Format is [Lookup Id]-[Encryption Passphrase]
Lookup Id = 20 character random alphanumeric string. Server generated.
Encryption Passphrase = 16 character random alphanumeric string. Client generated.
Corresponds to an encrypted RawEnv. Server stores Lookup Id, RawEnv public key signed by key creator, and RawEnv private key encrypted with Encryption Passphrase.