CBOR Credential Database Format

1. Introduction

The problem of storing secrets securely is an important part of credential management; unfortunately, most password managers and other applications managing secrets implement their own, and some times proprietary, credential database scheme.

This document proposes a new format for storing credentials at rest. The following goals are being pursued:

Extensibility: The format allows to add new capabilities to the file format over time, and third parties should be able to enrich the information embedded in the file with proprietary extensions, with tools unaware of newer extensions being able to ignore them.

Resilience: The format protects the data using state-of-the-art cryptographic algorithms to ensure the confidentiality and integrity of the protected data.

1.1. CBOR Grammar

This document uses the same grammar as used by [RFC8152]. The CBOR structures are described in prose.

bool

A boolean value (true: major type 7, value 21; false: major type 7, value 20)

int

An unsigned integer or a negative integer.

uint

An unsigned integer (major type 0)

nint

A negative integer (major type 1)

bstr

Byte string (major type 2)

tstr

Text string (major type 3)

map

A CBOR map (major type 5)

[+ FOO]

Indicates that the type FOO appears one or more times in an array. An optional empty array that is part of a map MUST NOT be serialized.

1.2. Conventions

Byte

A byte is a value in the range [0, 255] that can be represented with 8 bits.

Unsigned numbers

Unsigned numbers are represented as uN, a number in the range [0, 2^n - 1], e.g., u32 is a number between 0 and 4294967295.

Signed numbers

Signed numbers are represented as iN, a number in the range [-2^(N - 1), 2^(n - 1) - 1], e.g., i32 is a number between 2147483648 and 2147483647.

Endianness

All numbers are stored in the little-endian format, e.g., the u32 number 0x12345678 is stored as 78 56 34 12 consecutively in memory.

Byte sequence

A byte sequence is denoted as byte[N] where N is the number of consecutive bytes in memory.

UUID

Certain elements like ciphers and key derivation functions are encoded as Universally Unique IDentifiers [RFC4122].

URN

The human readable encoding of a UUID. In the context of CBOR this is encoded as a tstr.

String

A UTF-8 string.

2. Database Format

The CCDB data consists of a public and a confidential part. The database starts with a public header that encodes the properties of the database, including its version, followed by a encrypted block that contains the actual, CBOR encoded, data. The integrity of the header as well as the confidential block is verified using message authentication codes.

2.1. Outer Header

The outer header encodes information required to decrypt the remaining database. The overall structure of the outer header can be described as follows:

The header begins with the database version (§ 2.1.1 Version) followed by the length of the header fields in bytes, followed by one or more header fields (§ 2.1.2 Header Fields).

Note: The integrity of the header is validated by the selected AEAD cipher.

2.1.1. Version

The initial 8 bytes encode the CCDB version.

2.1.2. Header Fields

The § 2.1.1 Version is followed by a CBOR map (major type 5) of the following header fields. The keys are encoded as text strings (major type 3) whereas the value types vary. All listed header fields are mandatory and MUST be encoded in the order listed below.

2.1.2.1. KDF Parameters

The KDF parameters are used to derive a secret (§ 2.1.3.4 Symmetric Key). The $UUID is mandatory and defines which algorithm should be used as key derivation function. The other parameters are optional and depend on the selected algorithm. All parameters associated with the specified algorithm MUST be present for a specific algorithm, otherwise the database is malformed. The fields MUST be encoded in the order listed below.

2.1.3. Key Derivation

The encryption key is derived from one or more sources of key data:

• a § 2.1.3.1 Password,

• a § 2.1.3.2 Key File,

• or a § 2.1.3.3 Key Provider

2.1.3.1. Password

A password is the most common source of key data. It is set by a user during database creation and is also referred to as the master password. It is recommended to use a strong password that fulfill the criteria published by reputable authorities, such as OWASP and NIST.

It is further recommended that applications supporting the creation of CCDB databases further support the user with the creation of a secure master password, including the suggestion of randomized passwords.

2.1.3.2. Key File

A key file can serve as an input either alongside a password or as an alternative to the key derivation function used for deriving a symmetric encryption key. It’s recommended that applications support a range of key file formats to enhance compatibility and flexibility.

Applications SHOULD support the following key file formats:

• Raw: A file containing exactly 32 bytes that make up the key.

• Hex: A file containing exactly 64 bytes that are interpreted as a hex encoded 32 byte key.

2.1.3.3. Key Provider

Key material MAY also be obtained from other sources, e.g., using the HMAC Secret Extension of CTAP2 [fido-v2.1].

2.1.3.4. Symmetric Key

To generate a symmetric key, a key derivation function (kdf) is employed, which derives the key from either a password, key file or key provider. The input into this selected key derivation function is as follows, with its remaining arguments defined by § 2.1.2.1 KDF Parameters:

password || keyFileContent || keyProviderContent

It’s essential to ensure that the string passed to the KDF is not empty. Therefore, an application must enforce the usage of at least one of the following sources:

• password

• key file

• key provider

The process for deriving a symmetric key for encryption is as follows:

symKey = KDF(password || keyFileContent || keyProviderContent)

Note: It’s important to note that the length of the symmetric key must be adjusted according to the selected cipher (cid). For example, for AES256GCM, one can utilize the default hash length of 32 bytes for the symmetric key.

2.1.3.4.1. Argon2id + Password

I: 2, M: 4096, P: 8, S: 0102030401020304010203040102030401020304010203040102030401020304
password: supersecret

symKey = 1800b386aff0488a7a3720e014afd4b57d27c915ead08ed68ede40c225ce4e98 = Argon2id("supersecret")

2.2. Body

Directly after the § 2.1 Outer Header follows the body, consisting of the body length (u64), a tag, and the encrypted body data.

2.2.1. Body Data Structure

The body data is a nested CBOR map (major type 5) consisting of § 2.2.1.2 Meta, § 2.2.1.3 Group, and § 2.2.1.6 Entry data items.

2.2.1.1. Bin Entry

When a § 2.2.1.6 Entry is deleted it SHOULD NOT be removed directly but instead moved into the Bin. Moving a deleted entry in the bin allows the user to undo a deletion. Each application MAY define a limit after which a deleted entry is permanently removed from the database.

2.2.1.2. Meta

2.2.1.3. Group

2.2.1.4. Times

2.2.1.5. User

2.2.1.6. Entry

{
  1: 2, 
  3: -7, 
  -1: 1, 
  -4: h’299ba40f6547f9a591636ba3aabcf52adedeca324d3d6e81c8302d5199de9d0d'
}

A4            # map(4)
   01         # unsigned(1) # kty
   02         # unsigned(2)   # Elliptic Curve keys w/ x- and y-coordinate pair
   03         # unsigned(3) # alg
   26         # negative(6)   # ECDSA w/ SHA-256
   20         # negative(0) # crv 
   01         # unsigned(1)   # NIST P-256 also known as secp256r1
   23         # negative(3) # d (private key)
   58 20      # bytes(32)
      299BA40F6547F9A591636BA3AABCF52ADEDECA324D3D6E81C8302D5199DE9D0D

2.2.1.7. Attachment

2.3. Database Creation

Every application that supports the given standard should provide the flexibility to configure parameters that influence the behavior of the database. These parameters typically include the cipher, compression algorithm, and key derivation function. It’s recommended that applications only propose sensible values for ciphers and key derivation functions sourced from reputable authorities, such as OWASP and NIST.

By allowing configuration of these parameters, applications empower users to tailor their security settings to best suit their specific needs and environments. This adaptability ensures compatibility with various security protocols and standards, fostering a robust and customizable security posture for the application.

2.4. Serialization

During usage, the database typically exists in an intermediate form, largely contingent upon the programming language employed. Before persisting it to disk, the database must undergo serialization according to the following steps:

1. Serialize Header Version: Serialize the version of the header as specified in § 2.1.1 Version.

2. Header Field Length: Allocate 4 bytes to reserve space for the length of the header fields.

3. Generate Initialization Vector (IV): Create a new and unique initialization vector (iv), ensuring it is not reused.

4. Serialize the header fields, incorporating the iv.

5. Write Serialized Header Length: Record the size of the serialized header fields within the 4 bytes reserved in the previous step.

6. Encode the Body: The body is encoded as specified by the guidelines outlined in the § 2.2 Body section.

7. Serialize Body Length: Serialize the length of the body as a u64 data type.

8. Encrypt the Body: Utilize the cipher specified by cid to encrypt the body with the following parameters:

   • key: The symmetric key specified in § 2.1.3.4 Symmetric Key.

   • Initialization Vector (IV): iv

   • Associated Data (AD): The serialized header and body length.

9. Write Tag and Encrypted Body: Place the resulting tag immediately after the body length, followed by the encrypted body.

2.5. Deserialization

Before an application can use a database it has to be deserialized and decrypted according to the following steps:

1. Read Serialized Data: Retrieve the serialized data from storage.

2. Validate Version: Read the § 2.1.1 Version and validate that sig equals CCDB.

3. Extract Header Length: Extract the length of the header from the serialized data.

4. Extract Header: Extract the header based on the header length.

5. Validate Header: Validate that all required header fields are present and contain reasonable values.

6. Extract Body Length: Extract the length of the body from the serialized data.

7. Extract Tag and Encrypted Body: Extract the tag followed by the encrypted body from the serialized data.

8. Decrypt the Body: Utilize the specified cipher and associated parameters to decrypt the encrypted body:

   • key: The symmetric key specified in § 2.1.3.4 Symmetric Key.

   • Initialization Vector (IV): iv

   • Associated Data (AD): Outer Header || Body Length

9. Decode the Body: Decode the body according to the specifications outlined in the § 2.2 Body section.

3. Thread Model

3.1. Assumptions

3.2. Threads

3.3. Mitigations

3.4. Policies

The following policies SHOULD be considered by applications supporting the format defined within this specification.

3.5. Security Considerations

Files that store sensitive information are of particular interest to adversaries. The threads posed to a encrypted database change depending on its current state, including data-at-rest, data-in-transit, and data-in-use.

3.5.1. No Compression

Compression, in combination with encryption, may lead to unwanted behavior. Using CBOR as the main data format allows for a small message size making compression less relevant. This is why CCDB specifically doesn’t use compression.

3.5.2. No Double Encryption

Some file formats, like KDBX4, encrypt not only their main data but also specific fields such as password entries. The primary reason for this is to prevent the pollution of process memory with secrets, thereby making them more manageable. Assuming that the underlying operating system enforces process separation, including their allocated memory, and that the application protects the memory from being swapped out, the threat model involves an attacker with root privileges who can access process memory to obtain information about the decrypted data.

In the case of KDBX4, a problem arises when an attacker can read the decrypted XML data structure of a KDBX4 database located in main memory. In such a case, one must assume that the attacker can also read the prepended StreamKey. This allows the attacker to parse the XML data structure, collect all "protected" fields, and decrypt them using the StreamCipher with the StreamKey. Consequently, the fields are merely obfuscated, and the application cannot enforce the confidentiality of the data.

We, the authors of this document, believe that no confidential data should be processed on a compromised system and that there are no sufficient protection measures against an attacker with root privileges. Therefore, we assume a trusted processing environment in our threat model. Applications aiming to protect their data with a second layer of encryption should encrypt the data themselves and then store the ciphertext in the secret field of a § 2.2.1.6 Entry.

4. Recommended File Name Extension: .ccdb

The recommended file name extension for the "CBOR Credential Database Format" specified in this document is ".ccdb".

On Windows and macOS, files are distinguished by an extension to their filename. Such an extension is technically not actually required, as applications should be able to automatically detect the ccdb file format through the "magic bytes" at the beginning of the file, as some other UN*X desktop environments do. However, using name extensions makes it easier to work with files (e.g. visually distinguish file formats) so it is recommended - though not required - to use .ccdb as the name extension for files following this specification.