Key Messages
ORCA is secure by design.
In this Security Paper, it is conveyed how ORCA secures clients’ data, by describing the encryption of different data types (via cryptographic methods), the levels of access control available and the architecture of the data stored.
ORCA offers several unique layers of security which include:
- End-to-end encryption (confidentially via cryptography)
All the Account’s sensitive data is encrypted. All cryptographic keys are generated by the Users on their devices, and all encryption is performed locally. Consequently, only Users in possession of the appropriate keys can decrypt the data. Further details can be found in “Cryptography & Key Handling”.
- Double-encrypted in transport (confidentially in transit)
When the already encrypted Account’s data travels between the Users’ device and the ORCA servers, it is encrypted and authenticated by Transport Layer Security (TLS). Further details can be found in “Data Transport”.
- Least privileges access (confidentially via ACL)
Only Users with the appropriate permissions can see and possess the correct keys to decrypt each part of the data. Permissions are managed via the Access Control List (ACL). Further details can be found in “Access Control”.
- Reliable and unchangeable stored data (integrity, authentication and immutability via Cryptography and Hash Tree)
Every User’s Action leaves a trace, and its authorship can be cryptographically verified. Further details can be found in “Cryptography” under “Security Functionalities”.
- Users are time-independent (asynchronicity)
Users can perform Actions when other Users are offline.
- You have secrets. We do not. (zero-trust)
Only Users have access to their data. Users trust the data they read without having to trust the ORCA server. Neither ORCA nor our service providers can access the sensitive data the Users store at ORCA. Further details can be found in “Security Functionalities”.
- Restore and recover
In case of failure, disaster or data compromise, data can almost always be restored to a certain point in time. Further details can be found in FAQ - 1. How can data be restored?
The above is achieved by having the following design Principles in consideration:
- Never trust, always verify (“zero trust security model”)
In ORCA’s strategy and design, Users and devices are not trusted by default. This leads to specific implementation decisions such as strong identity verification, validating device compliance and ensuring least privilege access.
- ORCA’s ignorance
ORCA can never see, access or infer Users’ credentials and secrets.
- Only users share their data
No other party possesses the keys to share the data.
Additionally, the Users only share data that is not “hidden” (i.e. information not explicitly visible is not shared). Further details can be found in “Sharing data”.
- Everyone is entitled to security
ORCA is responsible for implementing and offering the highest level of security to their clients, even when the implementation complexity is out of the clients’ knowledge.
ORCA is responsible for informing their Users of any potential security gap in clear and understandable wording (e.g. storage of their Security Key).
- Transparency
ORCA welcomes external parties to examine our security implementation and commits ongoing efforts to make public our technological designs, together with the decisions and rationale behind the decisions taken. Additionally, any security-related compromise is communicated as soon as possible, where Users are given priority in the chain of communication.
- Security over functionalities
ORCA does their best to prioritise data security over functionalities. When this is not fully achievable, in rare situations where the data is not protected at all times (e.g. Upload via Email), the Transparency Principle is activated.
ORCA Application
Overview
ORCA provides software used by teams that enables them to safely store data in a structured format (such as complex ownership structure, transactions, file storage, etc.) whilst collaborating on this confidential data with internal and external parties to their organisation.
The teams are the data owners and ORCA is only responsible for storing it and ensuring its integrity.
The ORCA App is designed as a web application compatible with any modern browser.
Main Concepts in ORCA
The main concepts in ORCA are described below and further definitions are introduced throughout the document:
- ORCA - organisation;
- ORCA App - web application provided by ORCA;
- Account - a workspace where all the Users and data belong to;
- Users - a person identified by a verified unique email address that has access to an Account;
- Vault - subspace of collaboration between Users within one Account. An Account can have multiple Vaults;
- Account Owner - User with all the ultimate rights over one Account and that can not be removed. There is only one Account Owner per Account;
- Admin - a User who has access to all the Vaults and possesses additional rights, such as creating a Vault or inviting Users. One Account can have multiple Admins;
- Member - a User, invited to the Account by an Admin or Account Owner, with permissions to one or multiple Vaults;
- Role - a group of permissions a Member is given to each Vault by the Admin/Account Owner, which can be Edit or Read-only;
- Access Control List (ACL) - the mechanism through which the powers of a User are established. The powers are then enforced cryptographically, by the ORCA front-end or by the ORCA server;
- Cryptographic keys - secret chain of bytes, which when processed through a cryptographic algorithm can encrypt / decrypt data. See section Cryptography;
- Secret Key - a unique access key randomly generated by the User during the registration process which is never shared with anybody else. Without this key the User cannot decrypt any data from the Account. See section Cryptography;
- Action - any granular activity performed within the Account that describes what the Actor (User or ORCA) did, such as uploading a file or inviting a User. See sections Access Control list and ORCA’s Actions;
- Sensitive data - any data that is stored in the Account by its Users, such as Persons, Legal Entities, Assets and Files. A detailed description of Sensitive Data can be found in Privacy Policy;
- Operational data - data stored in the Account by its Users or ORCA that enables the ORCA App to ensure its immutability and to enforce access controls. This data is never sensitive, and examples of those are Vault ID, timestamps and Action types. A detailed description of Operational Data can be found in our Privacy Policy;
- Binaries - any File and Image uploaded into the Account. See section Data Types;
- ORCA front-end - code that runs in the User's browser. See section Connecting the dots & Security Scenarios;
- ORCA server - code that runs on ORCA App's infrastructure. See section Connecting the dots & Security Scenarios;
- ORCA Console - the first Account which is fully managed by ORCA. This Account enjoys the same security as a standard client Account, with additional functionalities such as overseeing other accounts and allowing new accounts to be created. See section ORCA’s Actions;
- Device - physical electronic equipment that is utilised by the User to access their Account via the browser;
- Trusted Device - a previously configured device where the User can access the ORCA App without inputting the Secret Key.
Security functionalities
Overview
Whilst the Access Control List (ACL) is how Users establish what other Users can see and do within the Account, those permissions are enforced with the following mechanisms: Cryptography, ORCA front-end and ORCA server’s validation. Additionally, ORCA’s data architecture (Hashtree) ensures the data is immutable.
In this section, it is explained how each mechanism is implemented, what level of protection it offers and how everything exists together.
Access Control List: User Permissions, Roles and Actions
In each Account, a User is uniquely identified by their email address. Within an Account, multiple Users can be granted different permissions. Every Action that the User can perform within the Account is pre-established by ORCA and depends on the permissions granted by an Admin or Account Owner.
There are three types of privileges with distinct levels of permissions.
A Member has permission to perform the following Actions:
- register (after receiving and accepting an invitation),
- log in,
- set up and manage their own two factor-authenticator,
- accept the request to change their email,
- regenerate their own Secret Key,
- manage their trusted devices (with the ability to add and remove),
- manage the data in the Vaults they were given permissions to (when they are given the Edit role to the Vault, instead of the Read-only role).
Additionally, a Member can see:
- their own data,
- the data within the Vaults they were given access to,
- the names and emails of the Users who wrote data in the Vault they have access to.
A Member is managed by the Admins and Account Owner and can be removed at any point in time (see section Handling Access & Sharing).
An Admin has permission to perform the following Actions:
- everything that a Member is allowed to,
- the basic Account administration, which includes:
- the ability to rename the Account,
- establishing whether two-factor authorisation is mandatory for all Users.
- manage Vaults:
- ability to create, rename and (un)archive (setting the Vault into read-only mode),
- read and write data to all the Vaults within the Account, and
- manage Integrations (see section API Integration: Addepar).
- management of Users, such as:
- ability to invite and delete Members and other Admins,
- ability to give, change or revoke Members’ access to Vaults,
- upgrade permissions from Members to Admins and vice-versa,
- edit any User’s name (excluding the Account Owner’s name - see section FAQ),
- trigger the User’s email change, and
- manage Users' trusted devices.
For further details see the section Handling Access & Sharing.
The Account Owner has the same permissions for Actions as an Admin, however, an Account Owner can not be deleted by another Admin.
Cryptography
This is the most technical section in this Security White Paper and it details the different cryptography strategies used, their purpose and implementation. We do our best to explain all the concepts understandably and state the consequences clearly.
Cryptography prevents actors who were not given the adequate cryptographic keys from reading the data, if they get a hold of it. It ensures that when a loophole in the software or policies is found and abused, the data remains secured via mathematical controls. And why is this needed? Within ORCA, our Users store sensitive data which is then communicated with other Users or external parties. This communication takes place in an open environment, uses technology where ORCA / Users sometimes have little to no control and where not all actors can be trusted, such as the Internet. ORCA understands that there is not such a thing as a fully secure system, but a well-designed system vastly decreases the probability of a successful attack.
Cryptography enables the sender (let’s follow the industry naming and call them Alice) to transmit data, by converting its readable version (plain text) to unintelligible text (ciphertext), which can then be securely transmitted, and deciphered by the receiver (from now onwards named Bob ), without a third party eavesdropping the message (from now onwards named Eve). For ORCA’s purpose, there is a fourth party who is a trustworthy confidant of both Alice and Bob (from now onwards named Carl) who helps create an increased level of trust.
The data is converted from plain text to ciphertext and back using a specific combination of cryptographic algorithms and keys. The keys are a secret ideally only known to Alice and Bob. When Alice and Bob use the same key (to encrypt and decrypt the data), the algorithm is of type symmetric. When two different keys are used it is referred to as asymmetric cryptography, where one key is used to encrypt and the other to decrypt. Usually, the keys in this keypair are named public and private.
Examining the cryptographic keys
In ORCA, there is a range of different algorithms and keys that are ORCA specific. They are utilised for one of the following purposes:
- sharing keys - asymmetric keys used to share the data between Users;
- encryption keys - symmetric keys used by Users to encrypt/decrypt the data;
- identity keys - asymmetric keys used to sign the transactions they write and ensure they are who they state;
- integrity keys - symmetric keys used to confirm the integrity of the data. This does not require the data to be decrypted, and only a hash is sufficient to validate that the data is not corrupted.
Now, we will go deeper into the Keys one by one (an overview can be found in Table 1 and Image 1).
![Image 1: Login cryptographic keys flow](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2F773b4d42-7eb7-434d-b48b-813509869bca%2F1.png?table=block&id=391cc72e-3f32-4613-8cfc-87360884fa27&cache=v2)
Secret Key is randomly generated by the User in their browser during the registration process. It is never shared with anybody else nor ever stored by ORCA. The Secret Key is used to encrypt other keys (i.e. private keys) stored in the ORCA server and for authentication. Without this key, the User cannot decrypt other keys and as a consequence any data from the Account.
The Secret Key comprises a 26+ size character string which is divided into two parts: a non-secret random Account ID (AID) and a secret sequence of 26 characters, denominated User Access Secret (UAS) (Image 2).
There are at least
![Image 2: Composition of Secret Key](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2F3394621a-7cd8-409f-9185-3579e6b35caa%2F2.png?table=block&id=8af6802f-b9bd-4b2b-b40f-634fe791ca15&cache=v2)
The Secret Key is essentially the holy grail of the keys. Once the User inputs the key in the ORCA front-end, two keys are derived directly in the browser from the UAS using the Hashed Key Derivation Function (HKDF) algorithm with different parameters: the Access Key and Challenge Key.
Challenge Key is a key generated by the User upon registration (see section Handling Access & Sharing) and it is used to authenticate the User following the standard challenge-response protocol and the hash-based message authentication code (HMAC). When the Challenge Key is generated during the registration process, it is stored in the database as plain text therefore being available to the ORCA server.
- The ORCA front-end sends the email address and the account ID information to the ORCA Server;
- The ORCA server asks the User to prove their identity by generating (and storing) a random 128 bit string and sending them to the ORCA front-end;
- The ORCA front-end, which is in the possession of the Challenge Key derived from the UAS, sends the challenge back together with the response: an HMAC of a challenge, using the Challenge Key as a Secret;
- The ORCA server, which is also in possession of the Challenge Key, validates the challenge-response accordingly, by calculating its result of the HMAC, and checking if they are the same.
See Image 3.
![Image 3: Authentication Flow](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2Fdcfd50e6-4836-418e-8e70-d060fc81555a%2FScreenshot_08-12-2024_13.07.07.png?table=block&id=a0a259b6-b37d-4124-8a1f-5698964e7ef3&cache=v2)
Once the User is authenticated, the ORCA server sends a package of encrypted keys, the Keys Package, which is decrypted using the Access Key. This package was saved by the user during the registration (see flow “Inviting a new User to the Account” under Handling Access & Sharing.
Access Key is a uniquely random key generated by the User during the registration process (see section Handling Access & Sharing. Its sole purpose is to encrypt and decrypt the Keys Package. The Access Key is never shared with anybody, it is privy to each User and only lives in the ORCA front-end.
The Keys Package contains the Identity Private Key and the Sharing Key.
Identity Private Key (IPrK) is a unique private key generated and signed by the admin, who invited the user. Its sole purpose is for Users to sign the transactions written, which are validated by its matching public key, the Identity Public Key (IPuK).
The Identity Private Key ensures that the User who writes the transactions is who they say they are. This is achieved by digitally signing the transaction using ECDSA keys.
- Alice possesses the IPrK and Bob possesses the matching IPuK. Both of the keys together are a unique keypair and both Alice and Bob have access to the Verify Algorithm;
- The IPuK that Bob received has been signed by Carl*, so even though it is public, it is ensured it is signed by the confidant party;
- Alice and Bob are communicating message X;
- Bob wants to ensure that the message honestly comes from Alice and not from an impersonator. Terrible things can happen if the message is from another person other than Alice and Bob would not then trust its content;
- Alice writes message X. Together with the content of message X, Alice includes another piece of information: her Signature, which is generated based on Alice’s IPrK and the content of message X;
- Bob receives message X. He now ensures the data is indeed from Alice by verifying the data, providing Alice's IPuK and the Signature and the content of message X;
- The verification is positive, Alice indeed wrote that message. Bob is relieved.
Sharing Private Key (SPK) is a unique random key generated by the User that is used to decrypt the other keys (i.e. application keys) shared with a user.
Application Keys are used to 1) encrypt and decrypt each piece of data within the Account and 2) calculate the HMAC for integrity purposes. Depending on the type of data, different keys are used: the Account Keypair, the Admin Keypair or the Vault Keypair. These keys are shared only with the appropriate Users depending on their access (see section User Flows).
The Application Keys are generated by asymmetric keypairs. For the actual encryption and decryption, a symmetric key is derived using the Diffie-Helman (DH) algorithm and the symmetric key is used to perform the actual encryption.
DH (public key + private key) = symmetric key (a)
Account Key is randomly generated by the creator of the Account (i.e. the first Account Owner) and it is shared with ALL the Users within the Account. It is used to d/encrypt the name of the Account and the Names of the Users (which are further secured via Access Control List). This key is rotated whenever a User is removed from the Account.
Admin Key is randomly generated by the creator of the Account and there is one per Account at each moment of time. It is shared with all the admins within the Account. It is used to de/encrypt the Vault keys and the Account keys. This key is rotated whenever the Admin is demoted within the Account.
Vault Key is randomly generated by the Admin who created the Vault. It is shared with all the Users who have access to this Vault. It is used to de/encrypt the Vault name and data. This key is rotated whenever a user is removed from a vault - this includes cases when an Admin or User is removed from the Account.
For each type of data stored, there is only one possible key that can be used.
Invitation Code is a random secret string generated by the Admin and shared personally (not via ORCA) with the invited User. It is required to build trust between the two Users (see flow “Inviting a new User to the Account” under section Handling Access & Sharing.
Invitation Key is derived from the Invitation Code generated by the Admin that invited the User and it is shared with the Admins within the Account. It is used to encrypt the initial secrets handed over to the User when they first accept the invitation (see flow “Inviting a new User to the Account” under section Handling Access & Sharing.
Invitation Access Key is derived from the Invitation Key - the same key material, just the “info” is set to User ID and the “salt” is the same as the one used to derive the Invitation Key. This key is used to prove to the ORCA server that the User has a correct Invitation Key before the ORCA server sends the encrypted invitation data (see flow “Inviting a new User to the Account” under section Handling Access & Sharing and Image 4).
![Image 4: Example of keys during a User invitation flow](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2Fecbf3422-3e57-4567-a073-315194eb2aaf%2F4.png?table=block&id=dfbf7f64-4646-4f6d-b087-4e4d21ec1d31&cache=v2)
Device Key is randomly generated by the User when adding a new trusted device, it encrypts the Identity Private Key, and it is privy to the User only. The key is stored only on the device, and the matching public key is saved in the ORCA server. During the login flow, the device proves the key’s possession, by signing a random challenge generated by the ORCA server (see section Accessing ORCA as a User (Authentification User Flow) - Add a new Trusted Device).
PIN Key is a key derived from user-defined PIN code on a trusted device. This key encrypts the private Device Key and Access Key. These keys are stored encrypted on a trusted device.
Ephemeral Key is used in combination with the Sharing Keys, when an external party i.e. ORCA server wants to write a piece of information, while having only access to the public key and data is required to be written in a write-and-forget manner. Examples of usage can be found in the Addendum.
When Alice wants to share confidential data with Bob, just by having his public sharing key, then:
1. Alice derives (DH) a shared key using a private Ephemeral Key with Bob's public Sharing key;
2. The shared key is used to encrypt data; 3. Alice sends the public Ephemeral Key together with the encrypted data to Bob;
4. Bob derives the shared key using the public Ephemeral Key and his own Private Sharing key;
5. Bob is able to decrypt the data using the shared key.
Combined Key is used in combination with the Sharing Keys when a party wants to write a piece of information and share it with a group (account, vault, admins, …), while having only the group’s public key and the data needs to be accessible later. There are two use cases for that (Image 5):
- When the Admin shares the keys with a User, then the combined user+admin key is derived (DH). When writing the data, the Admin derives the key using the Admin private key and the User’s sharing public key. When reading the data, the User derives (DH) the same key using their sharing private key and the Admin Public key.
- When the ORCA server is writing information to the account (see section ORCA’s Actions). The ORCA server is considered a special User without access to the Account, but with its own sharing keys. Only the ORCA server knows the private key, and the ORCA front-end knows the public keys. When writing data to the Account, the ORCA server derives (DH) a key using ORCA’s private key and the Account’s public key. The Account Users when reading the data can derive (DH) the same key using the ORCA public key and Account private key.
![Image 5: The Combined Key can be obtained from two distinct derivations](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2Fe10b27df-c5d2-44a7-9886-4fe19454dfcd%2F5.png?table=block&id=949fa502-2131-484c-8ad0-02242585962d&cache=v2)
Binary Key is randomly generated by the User when uploading a file to a Vault and it is saved as part of the Vault data, which effectively shares it with all the other Users that have access to the Vault. It is used to encrypt the file before uploading it and to decrypt it once it's downloaded. This key is used only once, meaning that it is unique per file.
Key | Purpose | Shared? | Source | Source Algorithm |
User Access Key (UAS) | key generation | No | Generated | |
Access Key | encryption, integrity | No | Derived (HKDF) from UAS | AES-GCM
HMAC |
Challenge Key | authentication | Yes, with the ORCA server | Derived (HKDF) from UAS | HMAC |
Identity keypair | signing | No | Generated by the admin who invited a user | ECDSA |
Sharing keypair | sharing other keys | No | Generated (initially by admin and later by user during registration) | ECDH |
Account keypair | encryption, integrity | Yes, across all Users | Generated | ECDH,
AES-GCM
HMAC |
Admin keypair | encryption, integrity | Yes, with Admins | Generated | ECDH,
AES-GCM
HMAC |
Vault keypair | encryption,
integrity | Yes, with Users within a Vault | Generated | ECDH
AES-GCM
HMAC |
Device keypair | authentication | No | Generated | ECDSA |
PIN-key | encryption | No | Derived (PBKDF2) from PIN | AES-GCM |
Binary key | encryption, integrity | Yes, with Users within a Vault | Generated | AES-GCM
HMAC |
Combined user+admin key | encryption, integrity | N/A | Derived (DH) from user’s sharing key and Admin keypair | AES-GCM
HMAC |
Combined orca+account key | encryption, integrity | N/A | Derived (DH) from ORCA server sharing key and Account keypair | AES-GCM
HMAC |
Invitation key | encryption, integrity, | Yes, with Admins | Derived (PBKDF2) from the Invitation code | AES-GCM
HMAC |
Invitation Access Key | authentication | No | Derived (HKDF) from Invitation Key
Info = User ID; Salt = Invitation Key derivation salt | HMAC |
Table 1: Summary of Cryptographic Keys specific to the ORCA App
Examining the cryptographic algorithms
As not all readers might be familiar with the details of the above outlined cryptographic algorithm, this section aims to provide a short introduction. It should be noted, however, that these do not provide an in-depth mathematical description and only serve the purpose of illustrating the concepts and goals behind the algorithms.
Algorithm | Input | Output | Parameters |
HKDF | High entropy secret | Symmetric key | Hash = SHA-512
saltLengthBytes = 64
|
PBKDF2 | Low entropy secret | Symmetric key | Hash = SHA-512
saltLengthBytes = 64
Iterations >= 1000000 |
ECDH | Asymmetric keypair | Symmetric key | - |
Table 2: Summary of Derivation Algorithms
Algorithm | Parameters | Type |
ECDSA | P-256, hash = SHA-384 | Asymmetric, Elliptic-curve |
ECDH | P-256 | Asymmetric, Elliptic-curve |
HMAC | SHA-256 | Symmetric |
AES-GCM | 256-bit
IV length = 96 bit
Tag length = 128 bit | Symmetric |
Table 3: Summary of Algorithms Users
MACs
A Message Authentication code (MAC) is a cryptographic algorithm that allows to perform data authentication given a symmetric key. If Alice and Bob already share a common key, they can use the HMAC algorithm to generate a cryptographically secure “checksum”
Key Derivation Functions
Firstly, there are two kinds of so-called key derivation functions that are used by ORCA: HKDF and PBKDF2. These functions serve different purposes and are used in different contexts. The general goal of a key derivation function is to transform an input into a bitstream that can be used as a cryptographic key. It is important to stress that KDFs generally do not increase the entropy of their input data. They are fully deterministic and do not randomly generate strong cryptographic keys. They rather leverage the entropy already present in their inputs and “stretch” it, so that (one or multiple) keys of a required size can be generated.
HKDF is a key derivation function based on the HMAC algorithm. The general idea is to use the HMAC construction (which in ORCA’s case is based on SHA-512) in an iterated fashion so that the input key material can be expanded to an arbitrary size. This is useful, as it allows you to generate multiple uncorrelated keys out of one piece of input data. Without access to the secret HKDF input, an attacker cannot (under common cryptographic assumptions) predict the function’s output. Furthermore, under common cryptographic assumptions, an attacker cannot use one part of an HKDF output to predict other parts of its output; this makes HKDF useful for “domain separation”, i.e., for generating different keys for different use cases that cannot be correlated to one another.
The PBKDF2 function is related to HKDF in the sense that it also serves the purpose of key derivation. However, as outlined above, key derivation functions in general do not provide their own entropy: if a low-entropy secret (i.e., something that might be easy to guess for an attacker) is used as an input to the HKDF function, then an attacker could mount a simple brute-force attack and “guess” the input that the HKDF function receives. PBKDF2 - amongst other functions - aims to improve this situation. While still being a deterministic function, its implementation can be tuned to be deliberately "slow". In other words, when using the right parameters, the function’s runtime can be tuned in such a way that one evaluation of the PBKDF2 function takes a certain amount of time (on some reference hardware platform). This enables the function to also be used on low-entropy input data, i.e., on data that an attacker might be able to guess within a relatively small number of attempts. For instance, if the attacker had (on average) to take one million guesses, and each guess would (due to the function being slow) take a computation time of one second, the overall process would require about eleven days of computation time for the attacker. This makes PBKDF2 better suited for low-entropy secrets like passwords that a user has to remember.
Signatures
Like message authentication codes, cryptographic signature algorithms serve the purpose of preventing attackers from changing messages exchanged between two or more parties without being detected. However, other than MACs, signature functions are asymmetric operations: two different keys are required for generating vs. for verifying a cryptographic signature. The key used for generating a signature is commonly kept secret, whereas the key required for verifying the signature can be made public. This is a common approach, for instance, used in TLS and other protocols.
The signature algorithm used by ORCA is ECDSA. It is based on elliptic curve cryptography, which is a commonly used scheme for building asymmetric cryptographic algorithms.
Key Exchange
The Diffie-Hellman key exchange algorithm is one of the seminal achievements in cryptography. It is an asymmetric algorithm that allows two parties to agree on a cryptographic key over a public channel. For this purpose, both parties each generate a secret and a public key (sometimes also referred to as “half keys”). The public keys are exchanged over a public channel, whereas each party keeps the secret key to themselves. The Diffie-Hellman scheme now allows both parties to combine their individual secret key with the public key they received from the other party; during this process, both parties will compute the same result. It should be noted that a plain Diffie-Hellman key exchange (i.e., without signatures or other protection measures) can be vulnerable to MiTM attacks. Such attacks are mitigated in ORCA’s case, by using cryptographic signatures.
Encryption
AES-GCM is the algorithm employed to encrypt data since it is commonly used and regarded as secure by modern standards. Particularly, GCM combines encryption (for providing confidentiality) with authentication (for preventing changes to the data). One important requirement (besides, obviously, keeping the used key material secret) when using GCM mode is to make sure the IV (Initialisation Vector) is unique. ORCA achieves that by using a timestamp (number of milliseconds since January 1st, 1970) as an IV. The timestamp itself (and the rest of the transaction) is generated in the ORCA client. But the uniqueness of a timestamp is enforced by the ORCA server. This ensures only one transaction can be saved at any moment in time, and all the transactions can be sorted chronologically.
In theory, there’s a chance that two users encrypt different content with the same key and the same IV. However, the second transaction won’t be saved, as the timestamp duplication will be rejected by the ORCA server.
For the Binary Key, the random IV is generated and stored together with the encrypted file.
Data structure architecture
ORCA stores all of the client’s data in one instance logically separated. The data is organised using a tree data structure, similar to Hash Trees (or Merkle Trees). Classical Hash Trees are a data structure in which each node contains a hash value of its child nodes; in a sense, such trees therefore propagate a hash of all stored data from the bottom (the leaves) up to the top (the root). ORCA’s architecture is similar in the sense that it also relies on a tree structure, which also incorporates hashes. However, other than classical Hash Trees, the variant used here does not propagate hash values from the leaves to the root, but rather the other way around: each node contains a hash of its parent node. Therefore, the data structure could also be described as a tree containing so-called hash chains.
The different concepts of the ORCA’s Hash Tree are:
- Transaction (node), and
- Hash Chain (one branch)
The Transaction represents each Action performed by the User or the ORCA (see section ORCA’s Actions). Every addition, modification and / or deletion to the data, is stored as one or multiple transactions. The Transaction aims to reflect the exact change that was performed. Each transaction is composed of the following information:
- data - the content (body) of the Action, which consists of two distinct parts:
- the confidential data (optional): the encrypted version of the sensitive data using one of the symmetric keys, and
- the plain text: non-sensitive data used to ensure ALC, such as the Action type, the index of the key used, etc. This is available for the ORCA server app to read.
- timestamp - an unsigned integer milliseconds from epoch, account -unique,
- Account ID - the unique Account identifier where the action was performed;
- version - an unsigned integer, used internally to identify the format of the field;
- appVersion - the internal version of the app which generated the transaction;
- previousHash - the hash (refer to point J.) of the immediate previous transaction;
- creatorId - the unique ID of the User who created the transaction,
- creatorIdentityKeyId - the ID of the Identity key used to sign the transaction. As this is stored, the keys can therefore be rotated in the future (not implemented atm);
- signature - the cryptographic digital signature (via ECDSA) created by the User based on all of the above fields (see Flow 2);
- hash - the cryptographic hash-based message authentication code (HMAC) of all of the above fields, using the appropriate keys of the Application Keys as the secret for its generation.
The user's ECDSA signature can be used to verify that the data in question has actually been written by the respective user. The additional HMAC demonstrates that this user also had access to the application key - i.e., that the user was a member of the account.
The first ever written transaction in each Account is referred to as the “Genesis” and has the following particularities:
- the creator is the Account, and
- the previousHash is set to an empty value.
![Image 6: Hash Chain basic visualisation](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2Fae8172c7-75db-48e8-b70f-b390183fba2e%2F6.png?table=block&id=f871be0e-8426-4fd0-8c00-15646e7655b3&cache=v2)
![Image 7: Tree Structure](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2F195346b9-e092-4c2f-96d2-67f1da14abac%2F7.png?table=block&id=6c383091-affc-4de2-a7ff-916d27666e99&cache=v2)
The hash within the transaction (point J. above) is in fact a Hash Chain structure (image 6), as it is built by the successive application of a hash function h(), n times to the input x and additional information
The following sequence of three different transactions can be established as an example of a Hash Chain:
T0 contains H0, which is created from content x and
In summary, the child transaction contains the hash which is used as a pointer to the parent transaction.
Our ultimate goal, the Hash Tree is effectively a hashchain where a parent can have multiple children (image 7). It can be described as multiple Hashchains combined:
T0 contains H0, which is created from content x and
![Image 8: Part of the Vault Branch in ORCA’s Hash Tree](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2Fa5211176-afa1-45b1-98c6-8f33fc8890bd%2FImage_8__Part_of_the_Vault_Branch_in_ORCAs_Hash_Tree.png?table=block&id=ac877bb6-56e4-419b-9030-a201137eb457&cache=v2)
In ORCA, an example of adding data to a Vault would take the following steps (Image 8):
- The User has access to the Vault A;
- The User reads the ADD_VAULT_DATA hash chain attached to the correct CREATE_VAULT transaction;
- The User creates some new data for the Vault;
- The data is encrypted and stored inside a new ADD_VAULT_DATA transaction;
- The new ADD_VAULT_DATA transaction is attached to the end of the hash chain.
ORCA server controls
The ORCA Server is responsible for different types of validations, for example:
- the latest Keys are used, such as Vault Keys;
- the parent transaction exists;
- the timestamp matches the real timestamp;
- the transaction type is allowed to be saved in that specific place of the chain;
- the transaction type is allowed to be saved by that User.
ORCA front-end controls
The ORCA front-end is responsible for limiting certain Actions and information to be disclosed to the User. This enforcement is performed in the User’s browser which is not fully within ORCA’s control therefore it is possible to be circumvented by Eve. Nevertheless, they are relevant as a first layer of prevention and in some cases to raise alerts. The ORCA front-end performs the following controls:
- Read-only mode
A User with read-only privileges will not have the options in the user interface to add, edit or modify the data. This is additionally enforced by the ORCA server.
- Hidden actions
There is a small number of actions and information that can be concealed from some Users, depending on their role. For example, whilst a User is granted access to visualise the data, the download buttons could be disabled, or the total number of Users within the Account is not displayed in the ORCA front-end.
- Invalid data
The ORCA front-end is also responsible for validating the information being read and written by the User. In every User’s logging, the ORCA front-end checks both for data integrity (for example that a new transaction was not injected in the data) and correctness (that the business logic was not bypassed).
Connecting the dots & Security Scenarios
The four main security mechanisms are combined to achieve an increased level of data safety and to avoid one single point of failure. For example, even if the ORCA server sends non-accessible data to the User, the User would not be able to decrypt it as they do not have the keys, or in the eventuality that the keys are shared, the ORCA server would validate if the User has the permissions to write (Table 4 and 5).
Contribute towards | |
Cryptography | confidentiality, zero-trust |
Hash Tree | immutability, integrity, zero-trust |
ORCA server | integrity |
ORCA front-end | Integrity, correctness |
Table 4: Overview of security controls
Layer | Technologies | Is the data encrypted? | Tasks Performed |
ORCA front-end | React,
Typescript,
comlink | no | Decrypts the data;
Validates the integrity and correctness of the data;
Performs business calculations; |
ORCA server | NodeJS (NestJS), PostgreSQL | yes | Data storage in a Hash Tree format, the plain part of the data validation |
Table 5: The two high-level layers of the ORCA App
Some examples of the scenarios that are mitigated with the above architecture are:
- The ORCA server is not able to read certain sensitive data within an Action;
- The ORCA server is not able to write data to the Account that is not allowed (see section ORCA’s Actions);
- The ORCA server is not able to write or manipulate data to the Account without the Users detecting it;
- Only Users with permission to a Vault can read its data;
- Users are not able to read data from a Vault and/or Account once their access is revoked (see flow “Revoke Vault Access” under section User Flows;
- Users are not able to add a transaction on another User's behalf (no impersonation);
- No data can be modified without Users detecting it.
All of the above applies to the ORCA server, and it is extendable to any malicious external actor taking control of it.
Whilst the following scenarios are serious security threats, ORCA can only do so much to mitigate them and this section serves simply the purpose of raising awareness of some of those:
- Quantum computers Depending on future technology breakthroughs, such as quantum computers, the current encryption algorithms might be broken. ORCA does their best to remain updated with the latest news on the industry, so Users can be informed accordingly.
- Impersonation Whilst no User can ever impersonate another User on their own, if the ORCA server and a certain User work together, this is possible, breaking the triangle of trust. For example, with the support of the ORCA server, an Admin could impersonate a user invited by this Admin.
- Deleting Data (Last transaction) Given a Malicious Actor gets on hold of the database, while they can not change the stored transactions or delete some transactions in the middle of the Hash Tree without being noticed, they can delete an arbitrary number of transactions in the chain as long as the transactions are at the end of the chain (not in the middle) without leaving a trace.
- Malicious User / Client From ORCA’s perspective, there is nothing that ORCA can do to prevent a malicious User that can access, modify, and share the data with third parties. Suggested mitigations to the Users: Be cautious about who you invite to the Account. If you ever face the situation of a malicious User, contact ORCA who can support you in the steps towards restoring the data to an uncorrupted state.
- Malicious actor in the possession of the User’s device When Eve is in possession of the User's device (either physically or by exploiting a browser or operating system vulnerability) while the ORCA App session is running, they can perform any action the User could. Suggested mitigations to the Users: Do not leave your device unattended and implement the appropriate mechanisms in your organisation to ensure your colleagues do the same. If you ever face the situation of a malicious Actor, contact ORCA who can support you in the steps towards restoring the data to an uncorrupted state. Observation: ORCA is nevertheless responsible for ensuring the appropriate session termination and enforcing mechanisms are in place.
- Limited re-encryption in revocation Revoking access from a Vault or an Account prevents them from accessing future data, but the keys stored are not changed for stored data. So when the User makes a copy of the data, they are able to decrypt it with their old keys. Suggested mitigations to the Users: Be cautious about who you invite to the Account.
- Malicious actor injecting code in the ORCA App When Eve successfully executes a malicious action such as hijacking ORCA’s development pipeline, changing the network configuration to serve different content or attacking a provider in ORCA’s vendors' list, she can deliver malicious front-end code to the users, and as a consequence gets a hold of the keys and/or sensitive data. Observation: ORCA follows the most up-to-date industry practices in the development of ORCA App.
- Vulnerability of server data Our data hosting provider can leak or share the stored data. However, as the sensitive data is encrypted, the consequences of such an event are significantly reduced. See more in our Privacy Policy on which data is not encrypted.
User Flows
In this section, the most relevant flows security-wise are described, including steps from the User and the technical perspectives. From an implementation point of view, an atomic save is achieved by generating all the transactions at the ORCA front-end first and then sending all of them in one batch to the ORCA server, which then performs additional checks on the plain part of the data (see section ORCA server controls).
Here we divide the flows into groups, one focused on how the User accesses the Account and another on how Users can receive additional information not yet shared.
In some of the flows, a One Time Password (OTP) generated by the ORCA server using a 12-characters random string is used to confirm a certain User has access to the email account. The OTP is generated and stored by the ORCA server in plain text, and when the User performs a pre-established Action such as clicking on the link in the email, then the ORCA front-end sends the OTP in plain text to the ORCA server (note that TLS is used as mentioned in FAQ), where the verification happens.
Accessing ORCA as a User (Authentication User Flow)
Creating a new Account
The permission to create an Account is granted by ORCA based on an email address. Before creating an Account, the ORCA server performs a check on whether the email address can actually create the Account.
When a new Account is created, the following flow takes place:
- Via the ORCA console, the ORCA team enables the email address of the Account Owner to create an Account. A transaction is written in the ORCA Console by the ORCA server;
- The ORCA server sends an email with a validation link to the Account Owner’s email address. The validation link is valid for 15 days and contains an OTP;
- The Account Owner clicks on the validation link from the email;
- The Account Owner inputs the name of the Account;
- The Secret Key is generated and displayed to the Account Owner;
- Other initial keys i.e. Account key and Admin key are generated and saved;
- The Account and the Account Owner are created.
If for any reason step 6. fails, the Account Owner can recreate all of the steps from the beginning, since there is nothing permanently saved.
Login
Whenever the User wants to login into the ORCA App, the process described in Flow 1 (see section Cryptography) takes place.
Adding a new trusted device
In a trusted device
The PIN Code is a device-specific string defined by the User, with a minimum number of six characters that is used to d/encrypt the Private Identity Key which is encrypted and stored in the device (the Public Identity key is stored in the ORCA server).
When setting up a new trusted device, the following flow takes place:
- The User initiates the login flow in the ORCA front-end, as described in Flow: Login;
- During the login flow, the User is prompted to save the device as “trusted”. If the User agrees, the Device Key pair is generated, and the public key is stored in the ORCA server;
- The User is prompted to define the PIN Code
;
- The Device Private Key and Access Key are stored on the device (encrypted with a Key generated based on PIN Code);
- The Public key is stored in the ORCA server.
Observations: in the future, additional authentication factors can be included in this process, such as email confirmation, a one-time password generator, a physical key, etc.
Accessing the Account via a Trusted Device
Given a User has set up a Trusted Device, when accessing from the same browser, they are prompted to input the PIN Code to initiate the identity validation and the keys decryption process.
When accessing the Account via a Trusted Device, the following flow takes place:
- The ORCA front-end identifies that there are one or multiple devices stored;
- The ORCA front-end prompts the User to select the Account and asks for PIN Code, to be able to decrypt stored keys;
- The User inputs the PIN Code;
- From the PIN Code, the symmetric key is generated (PBKDF2);
- The ORCA front-end fetches the stored keys from on-device storage, and decrypts them;
- The ORCA front-end makes a request to the ORCA server to initiate the session claiming possession of a certain private key;
- The ORCA server generates a random challenge, saves it and sends it to the device;
- The Trusted Device signs the challenge using the Identity Private Key, and sends it to the ORCA server;
- The ORCA server validates the signature against the stored public key;
- If validation passes, a transaction containing the other User’s secrets encrypted is sent to the ORCA front-end.
Setting two-factor authentication
Either because the Admins of the Account established that two-factor authentication is mandatory, or because the User wants to set it up, the two-factor authentication via an authenticator app is made available per User.
When the User sets up the two-factor authentication, the following flow takes place:
- The User initiates the two-factor setup;
- The ORCA front-end generates the authenticator secret and displays it to the user in a QR code form;
- The User scans the QR code using their authenticator application;
- The User inputs the time-based one-time password (TOTP) provided by the authentication application and submits it;
- The ORCA front-end verifies that the code provided is valid - meaning user has successfully set up their authenticator application;
- The authenticator secret is encrypted with the Combined Account and ORCA Sharing keys and stored in the ORCA server, so it can be read and used to verify the TOTP during the login process.
Handling Access & Sharing
Inviting a new User to the Account
When the User Bob is invited to the Account by the Admin Alice, then trust is required to be established between the User and the Admin asynchronously where the Admin shares secrets, such as the Vault Key with the new User even before the invitation is accepted.
When Alice invites Bob to the Account then the following flow takes place:
- Alice specifies Bob’s identity, by setting the email and additional information such as the name;
- Alice generates the initial Sharing Keypair for Bob;
- Alice generates (and signs) Bob’s Identity Keypair.
- The Invitation Code is generated and the Invitation Key is derived;
- The Initial Sharing Private Key and Identity Private Key are encrypted using the Invitation key;
- The Invitation Access Key (HMAC) is derived and stored in the ORCA server;
- The ORCA server sees Bob is invited and then generates and saves the email confirmation code (OTP);
- An email is sent to Bob with the email confirmation code where the Account ID, Bob’s ID and the confirmation code are encoded into the registration link;
- Alice shares the Invitation Code with Bob using a different communication channel (i.e. phone/text);
- Bob opens the email, clicks on the registration link;
- The ORCA front-end is launched in the browser and a request containing OTP is made to the ORCA server to access the invitation;
- ORCA server validates the OTP, and creates a signature confirming that this email address is used by the specific user. Additionally, it generates and saves an access challenge (random 128 bits Challenge and signature are sent back together to ORCA front-end;
- The ORCA front-end requests Bob to input the Invitation Code shared by Alice;
- Using keys derived from the Invitation Code, Bob signs a challenge and sends it to the ORCA server. By doing so, Bob proves to the ORCA server the possession of the Invitation code, without disclosing it;
- The ORCA server sends the invitation transaction, and Bob can decrypt it using the Invitation Key derived from the Invitation code;
- Bob has now access to the Account!
- Bob rotates his Sharing Keypair, so the Private Sharing Key is known only to him.
In this flow, a triangle of trust is established such that:
- Alice and Bob have a shared secret (invitation code);
- Bob confirms to the ORCA server that he has access to the email account; ORCA server generates a signature stating this fact, which can be verified by other users;
- The Account Owner is the root of trust: the Users can always trust who invited them and the Account Owner (this is a similar approach to the root certificate authority in Public Key Infrastructure - PIK
).
Granting a User access to the Vault
When Admin Alice invites User Bob to a Vault, then the following flow takes place:
- Alice specifies Bob's role in the Vault, which can be an Editor or Reader;
- Alice updates the ACL accordingly;
- Alice shares all Private Vault Keys with Bob.
Revoking Vault access
When Admin Alice wants to remove User Bob’s access from a Vault, then the following flow takes place:
- Alice updates the ACL accordingly;
- Alice generates a new Vault Key and encrypts it with the Admin Key such that all Admins can read it;
- Alice shares that new Vault Key with all the existing Vault Members (and not with Bob);
- Alice informs all Admins and Users with access to that Vault that Bob’s access to the Vault has been revoked.
Removing a User from the Account
When Admin Alice wants to remove the User Bob from the Account, then the following flow takes place:
- Alice updates the ACL accordingly by deleting Bob;
- Alice generates a new Account Key, new Vault Keys for the Vaults Bob had access to and in case Bob is an Admin a new Admin Key is also generated;
- Alice shares those Keys with the relevant Users;
- Alice informs all Users that Bob has been removed from the Account.
Observation: a similar process takes place when a User is demoted from Admin to a Member.
Sharing data with external parties (without a password)
When Alice wants to share data with an external party Bob, then the following flow takes place:
- Alice selects which data is to be shared with Bob e.g. file with ID = 1, entities with ID=2 and 3 and ownership transaction with entity ID = 4;
- The Sharing Keypair is generated, such that the private key is encrypted with a Vault Key, the public key stays in plain text, and both are then stored in the ORCA server;
- The shared data is encrypted with a key derived from the Sharing Keypair,
- The Private key is stringified in the URL, shared with Bob by Alice;
- Bob accesses that URL;
- The ORCA front-end makes a request to the ORCA server to start a session claiming the possession of the private key;
- The ORCA server generates a random challenge, saves it and sends it back;
- The User signs the challenge using the private key and sends it to the ORCA server;
- The ORCA server validates the signature against the stored Public Key;
- If validation passes, a transaction containing shared data is sent;
- Bob decrypts the data using a symmetric key derived (DH) from the private and public keys.
Sharing data with external parties (with password)
When Alice wants to share data with the external party Bob which is protected by a password, the following flow takes place:
- Alice selects which data is to be shared with Bob e.g. file with ID = 1, entities with ID=2 and 3 and ownership transaction with entity ID = 4;
- Alice defines a password (with a minimum and max length of 4 and 255 respectively), and the random PBKDF2 parameters are generated;
- From the password, a Sharing Access Key (HMAC) is derived (PBKDF2, then HDKF);
- The Sharing Keypair is generated. The Sharing private key and password are encrypted with a Vault Key. The Sharing public key, the password derivation parameters and the Sharing Access Key stay in plain text. Everything is stored in the ORCA server;
- The private key is stringified in the URL, shared with Bob by Alice, Bob accesses that URL;
- Alice shares the password with Bob outside ORCA;
- The ORCA front-end makes a request to the ORCA server to start a session claiming the possession of the private key and password;
- The ORCA server generates a random challenge, saves it, and sends it back together with the password derivation params;
- The User signs the challenge two times (once by using the private key, and a second time by using the HMAC derived from the password) and sends it to the ORCA server;
- The ORCA server validates the first signature against the stored Public Key and the second against the stored HMAC;
- If the validation passes, a transaction containing the shared data is sent;
- Bob decrypts the data using a symmetric key produced from a hashed key material from:
- Symmetric key derived (DH) private key and public key, and
- Symmetric key derived (PBKDF2) from password.
![Image 9: Simplified visualisation of Symmetric Key](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2F009af702-26e4-45f0-9739-7f3b529e5a36%2F8.png?table=block&id=395e186d-8cd7-4721-9975-697bbcd51a03&cache=v2)
ORCA’s Actions
There are a limited number of Actions that the ORCA server is allowed to write into the clients’ Accounts.
Those Actions are validated cryptographically and via the hash tree. The ORCA server uses Combined Account and ORCA sharing keys when writing these transactions.
The Actions are limited to:
- Attempts before login
Whenever a user tries to log into the ORCA the information is saved - including login, trusted device access, and session renewal.
- Inactivate the Account
Via the ORCA Console, the ORCA team can manage the Accounts, such as setting an Account to inactive. Once this Action is performed, a transaction is written both in the ORCA Console and the Account with Account keys and the Users are prevented from accessing the Account.
- Deleting all data within an Account
On request by the Account Owner and/or upon the cancellation of the subscription, ORCA can delete the Account information, by deleting the appropriate chains. This process follows strict controls and it can only be triggered for Accounts that have been inactive for longer than 15 days.
- Manage the two-factor authentication setting in an Account
Via the ORCA Console, the ORCA team can de/activate the two-factor authentication from being mandatory in an Account. This does not impact the already established two-factor configurations of the Users in the Account. Once this Action is performed, a transaction is written both in the ORCA Console and the Account.
- Remove a User’s two-factor authenticator within an Account
Via the ORCA Console, the ORCA team can remove the two-factor authentication configured by a User in the Account. Once this Action is performed, a transaction is written both in the ORCA Console and the Account.
- User email confirmation During the registration process, when the invited User clicks on the registration link (see section Handling Access & Sharing) the email is confirmed. Additionally, via the ORCA Console, the ORCA team can confirm the User’s email as well. Once this Action is performed, a transaction is written both in the ORCA Console and the Account.
- Ability to de/activate available functionalities in the Vaults Via the ORCA Console, the ORCA team can establish which functionalities are available in each Vault per Account, such as Integrations, Cash Flows, Automatic Completeness Checks, etc. Once this Action is performed, a transaction is written both in the ORCA Console and the Account.
- Billing information
Whenever a transaction is written by the User in a Vault, the ORCA front-end calculates the information required for billing (such as the number of Persons within a Vault, for complete details please refer to our Privacy Policy) and stores this information. ORCA server copies that information later to the ORCA Console account.
None of the information included in the transactions written by the ORCA server is encrypted.
Data Types
The Vault is a central place of collaboration within ORCA. Users with a given access can write data into a Vault in an append-only manner. As a consequence, ORCA does not have to store the "audit log" of the Users’ actions as the Vault data itself is the audit log of all the Actions.
Actions are the granular behaviours performed by the Users within an Account and / or a Vault, such as creating an Asset, deleting an Event, etc.
The ORCA front-end, after decryption and verification, produces all the data items Users see and manage on screen such as entities, events, meetings etc.Image 10: Brief visualisation of the stored data
![Image 10: Brief visualisation of the stored data](https://www.notion.so/image/https%3A%2F%2Fprod-files-secure.s3.us-west-2.amazonaws.com%2Faba5529a-e8ff-4d4c-b470-a458e68a7de3%2F74f929a7-dd8e-40ee-97f4-b3cd61ab3f1f%2F9.png?table=block&id=b7d94941-263b-45fd-a0ef-9bffe67f7f0b&cache=v2)
One of the possible Actions is to upload a File or to upload an Image associated with an Entity. Files and Images are referred to as Binaries.
When a Binary is uploaded, the appropriate Action is stored with the related meta information whilst the Binary content is uploaded into an external storage off-chain. This enhances the performance of transactions’ load and processing while enabling the Users to still navigate in the list of Binaries within the Vault.
When the User uploads a Binary from their desktop, the following steps take place:
- The Binary is loaded in the ORCA front-end;
- The ORCA front-end encrypts the Binary with the appropriate Binary Key;
- A random UUID is generated by the ORCA front-end;
- The upload starts and the ORCA server validates if the User has access to the Vault;
- The upload finishes and a transaction ("upload done") is saved to the chain, with the Binary’s metadata.
Note that the ORCA server cannot investigate the contents of the uploaded Binaries (for example against viruses), as the Binaries’ content is never available to the ORCA server.
To effectively bill the clients, ORCA tracks the number of items (i.e. contacts, assets etc.) within a Vault, under the Billing data. Every time a User performs any write Action into the Vault, the ORCA front-end calculates the current number of items according to the Privacy Policy and when the number has changed then it sends it in plain text to the ORCA server and it is stored in the Account Chain and copied to the ORCA Console. The ORCA server does NOT validate this data, since it has no data to perform such validation. As a consequence, ORCA has access to the Billing information.
Addendums
There are certain functionalities where additional information is required to be opened to ORCA for a limited period of time. For each of those, the User is required to explicitly opt-in per Vault.
Upload via Email
Once the Upload via Email is activated in a Vault, the Users can send files to that ORCA Vault via a dedicated email address.
The Upload via Email functionality is activated following the steps:
- An Admin in the Vault requests the functionality to be activated;
- Before activation, the User is prompted with a description of the potential security risks;
- The User is prompted with a unique email address e.g. orca-vault1-aed@withorca.com.
When Alice sends an email to the ORCA Vault, the following steps take place:
- The ORCA server establishes a long-living connection with the mail server via Internet Message Access Protocol (IMAP) checking for new emails every five minutes;
- When an email arrives in the inbox, the ORCA server matches the Account ID and the Vault identifier parameters;
- ORCA server validates whether the sender’s email address is allowed to send emails in this Vault
- The ORCA server downloads the Files from the mail server;
- The downloaded File is uploaded to the specific Vault, where the transaction is encrypted using the Ephemeral Key, based on Vault's latest public key;
- The email (with all the attachments and content) is deleted;
- All Vault Users can see the File as "Uploaded by ORCA" and the sender's email address.
Due to the nature of how email protocol works, ORCA cannot guarantee full security and end-to-end encryption, in contrast to the standard upload of Files performed within the ORCA App, in particular:
- ORCA has the means to see the contents of the email sent, while it is not yet processed. ORCA immediately deletes the emails and their content once they are processed
;
- the security of the Users’ email provider is not ORCA's responsibility;
- the security of the Users’ email while being transferred in the Internet is not ORCA's responsibility;
- ORCA, together with our service partners, is responsible for ensuring the connection between ORCA’s email and ORCA is secured.
In case of errors during the emails’ processing, a communication email is sent to the sender and the email content is immediately deleted which can occur in the following situations::
- when the User is not allowed to send emails to that Vault / dedicated email address;
- when the Vault dedicated email address does not exist;
- when the email content contains no attachments;
- unknown error for any other situation e.g. ORCA server is not available, email parsing failed, etc.
Observations:
- The ORCA server (and/or its partner) performs all the possible checks against email sender impersonation i.e. SPF, DKIM and DMARC;
- By default, only Vault Users with Editor rights (including Admins) are allowed to upload Files by email. It is however possible to develop a dedicated allowed list of emails for non-Users managed by the Account Admins;
- ORCA does not investigate the contents of the uploaded files, i.e. against viruses.
API Integration: Addepar
The Addepar integration enables the ORCA server to pull data from the Addepar API, process it, and then add it to the Vault (for logical details on the Integration see the article here).
The Addepar integration is activated following the steps:
- The Admin chooses a Vault and initiates the integration flow;
- The Integration ID is generated and saved with integration meta information;
- A Challenge is created by signing the Integration ID using the User’s Identity Private Key;
- A new browser tab is opened using the Addepar OAuth flow URL together with a pre-established ORCA state (which includes for example the accountId, the vaultId, the challenge, etc.);
- After the User logs in into Addepar, reviews and confirms the integration all in the Addepar browser tab, Addepar calls the ORCA server with the previously passed state;
- The ORCA server finishes the OAuth flow by retrieving a refresh token and also verifying the challenge and additional parameters;
- The ORCA server stores the encrypted refresh token to the Vault, but using a combined key. The refresh token will later onwards be decrypted by the ORCA server to perform updates.
The ORCA server retrieves data from Addepar periodically and when manually triggered by a User within the ORCA app. The data retrieval is done by following the steps:
- The ORCA server validates the integration is enabled;
- The ORCA server reads the refresh token from the database and uses it to obtain an access token for the Addepar API;
- By using the access token, the ORCA server fetches the relevant data from the Addepar API and processes it;
- The ORCA server saves the data into a vault using a Vault Ephemeral Key.
During the data processing, ORCA has read-only access to the Addepar data. However, no sensitive data is logged nor stored anywhere else than in the specified Vault. After adding the data into the Vault, ORCA can no longer access it.
FAQ
- How can data be restored? There are two different approaches to restoring data in case of failure or inconsistency which are to be used in distinct scenarios:
- data backups: occur every night and are kept for 7 days
- data rollback: in case of a malicious user, there is a possibility to remove all Vault transactions saved after a certain moment in time.
Our backups are fully and automatically managed by our hosting provider, which has a disaster recovery plan. The backups are created within a 24h interval, therefore any data added in between will not be recovered.
- Who can edit the username of a User? Any Admin or Account Owner can edit the username of a User, including other Admins. Only the Account Owner can edit their own username.
- How can the User keep the Safety Kit secure? Refer to the article here.
- Which vendors are used? For the whole list of our vendors, such as hosting or file storage, please refer to our Privacy Policy.
- Does ORCA use encryption on transport? ORCA uses industry-standard Transport Layer Security (TLS), for any data transported from/to the ORCA server and to/from the ORCA client. The ORCA server is configured to redirect all insecure HTTP requests to HTTPS (HTTP over SSL/TLS). Some examples of usage are when:
- Fetching ORCA client code by the browser;
- Fetching data from ORCA server;
- Sending data to ORCA server.
Changelog
v1.1 - 2024-08-15
Adjusted images to be in line with ORCA branded assets. No content was modified.
v1 - 2024-04-01
First public release of the new ORCA architecture. A completely new paper is launched.
Externally verified by Securitum and Secfault Security. See the reports here.
v0 - 2020-06-20
First Security Paper where ORCA supports multiple Users within one Account and Users are independent from Accounts.