Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

dpm-identity

The dpm-identity repo is a store of identities and audits that is being implemented as a part of this proposal. The repository aims to manage identities and audits in a way that gives assurances that each identity is who they say they are, and each audit has come from a valid identity. This will allow users to decide which auditors they trust statements from. The identity store shouldn’t make any guarantees about the security of artefacts generated by identities; this decision will be made by the users themselves via the tooling we provide in later milestones.

Repository Objectives

Work on this repository can be split into two stages:

  • Milestone 1: Create the repository with multi-key signoff enforced.
  • Milestone 7: Ensure that the repository has mature governance processes that scale as the project expands.

This documentation currently satisfies M1, however we are currently working with Digital Asset to agree on the later governance processes, and we will highlight M7 features wherever they are planned.

M1 Documentation

The documentation required for submission of M1 is as follows:

  • Submission and review workflow documented here
  • Verification process here

Repository Specification

The following gives a statement of intent for the repository across ALL milestones:

We wish to create a store of identities and audits for the Daml Package Manager project. The identities will be used to identify auditors and publishers in the infrastructure we are designing as a part of this proposal. They should be managed in a way that gives assurances that each identity is who they say they are. This will allow users to decide which auditors they trust statements from. The identity store shouldn’t make any guarantees about the security of artefacts generated by identities; this decision will be made by the users themselves. Any assurances surrounding an identity will be backed up with evidence, and a clear policy will determine whether this evidence is sufficient. This evidence will then be stored in the repository git tree. A security policy will be enforced by gittuf, which will log all commit activity in an append-only log. An elected committee will vote on decisions, which will also be auditable via gittuf.

Identities

An identity in the repository is exactly one GPG key. Thus an organisation authoring packages must sign these packages with their single organisation key. Likewise an auditing organisation must sign their audits with their key.

Audits

An audit should classify a particular Daml artefact as safe or unsafe. This classification should be signed and dated by an identity in the repository.

The Committee

Any notion of trust in the repository stems from the committee. No one else is given the ability to modify identities, which in turn decides who can add audits. The initial committee comprises two members:

  • Canton Foundation
  • Obsidian Systems

Each of which will be associated with a GPG key, representing the member’s vote. The committee members have a responsibility to keep the keys safe: they are the source of trust for the repo. We would advise generating a primary key on an air-gapped machine, then exporting a subkey to use.

Gittuf Policy (M1)

These rules will be enforced by gittuf policy. The specific policy in effect for M1 is:

  • obsidian-systems and canton-foundation are both registered as Policy Administrators and in the Root of Trust (see gittuf docs for a description of these roles). Among other things, this means that they can propose new policies, AND add new Policy Administrators.
  • There is a threshold of 2 of 2 votes for every Root of Trust operation and Policy Administrator operation in the repository.

The current policies in effect are:

  • Modification of any files not under the audits/ folder requires 2 of 2 votes from the committee.
  • Modification of files under the audits/ folder can be done by anyone, provided that they have been registered in the repo. This has been done manually for now, but when (M7) is started, there will be an automated process for this.

To verify this policy for yourself, see the notes here.

Adding to the committee (M7)

The proposal outlines a small initial committee, but as the repository expands in size, we will need to think about adding more members to the committee and additionally changing the threshold of votes required for certain operations. Adding a new committee member is a much more dangerous operation than just adding keys. We will need to have tighter checks to ensure a committee member is who they say they are AND can be trusted. This could mean verifying in-person. This will be properly formalised in the later milestones.

File Structure

The file structure we propose is:

identities/
    <id>/
        meta.json
        FA31...A3/
            key.asc
            evidence/
                ...
        B491...D5/
            key.asc
            revoke.json
            evidence/
                ...
audits/
    <package-id>/
        <identity>-<date>.json
        <identity>-<date>.json.sig
        <identity>-<date>.revoke.json
        <identity>-<date>.revoke.json.sig

Where:

  • identities/ contains directories corresponding to each identity in the repo
    • <id>/ is a directory containing the history of all keys for an identity. The naming convention here is that <id> is the kebab-case version of the Name field of the gpg keys.
      • meta.json: Metadata about the identity
      • <key>/: Directory containing information about a particular key
        • key.asc: The exported GPG public key. Generated via gpg --export --armor
        • revoke.json: A JSON file indicating that the key has been revoked and why.
        • evidence/: Directory containing evidence used by the committee when evaluating the key’s identity
  • audits/ contains subfolders corresponding to package ids:
    • <package-id>/ contains all audits of a package id
      • <identity>-<date>.json is an audit of <package-id> by <id-fp> on <date>. Note: No claims are made by this filename, it’s solely to reduce collisions. All of the significant content is contained within the file. It conforms to the specification outlined in schemas/audit-report.json5.
      • <identity>-<date>.json.sig is the detached signature of the audit.
      • <identity>-<date>.revoke.json expresses a revocation of the audit.
      • <identity>-<date>.revoke.json.sig is the detached signature of the revocation.

We decide that a key for an identity is valid by checking that it hasn’t been revoked.

Submission Process

Currently any changes to the repository need approval from 2 of 2 of the following committee members:

  • Canton Foundation
  • Obsidian Systems

This is dictated by the repo’s gittuf policy (see here for specifics). As we have initially elected to allow using gitthub authentication to verify one’s identity, the approval process will take place in GitHub via a PR. One positive review corresponds to one approval vote.

The submission process is as follows:

  1. A submitter (anyone) opens a GitHub PR, containing the changes to the repository.
  2. The submitter requests a review from both committee members (Canton Foundation and Obsidian Systems).
  3. The committee members each decide whether the changes are appropriate (see below), and approve/deny the review.
  4. Anyone merges the PR.

For an example PR, see here.

Governance and M7

Note that in step (3), we haven’t described an explicit set of rules to decide what “changes are appropriate” means. This explicit policy is a priority for later milestones (specifically Milestone 7), as currently the identities in the repository will not change. We are in the process of formalising a governance policy together with Digital Asset. The draft policy can be found here.

The current roadmap for M7 includes:

  • A decision tree that governs whether to add keys to the repository. This should make explicit the valid forms of identification.

  • A secure process for various key and audit removal processes:

    • Rotating keys
    • Removing a compromised key
    • Reporting a lost key
    • Removing a malicious actor from the repo
    • Removing a bad audit

    Outlining in each case what happens to audits in the repo.

  • A CLI tool that can be used to aid common processes

Verification Process

Currently the repository’s security policy amounts to checking that the working tree satisfies gittuf policy. Ensure that gittuf is installed, that gpg signing for commits has been enabled, and that the repository has been cloned via:

gittuf clone https://github.com/daml-community/dpm-identity.git

NOTE: cloning via gittuf is important, as it pulls the correct git refs.

Listing the gittuf policy

Ensuring that you have followed the instructions above to install gittuf, gpg and clone the repo, the gittuf policy can be listed via running:

To list all principals

gittuf policy list-principals

To list all rules

gittuf policy list-rules

Verifying the gittuf policy

Ensuring that you have followed the instructions above to install gittuf, gpg and clone the repo, helper commands are provided to check that the repo satisfies gittuf policy. Run the following:

Linux/macOS

From Bash:

sh ./ci/verify.sh

Windows

From PowerShell:

.\ci\verify.ps1

A practical demo

The following demonstrates a user violating this policy by creating the files:

  • identities/my-id/meta.json
  • identities/my-id/my-fp/key.asc

without the changes being approved by two committee members. Ensuring that you have followed the instructions above to install gittuf, gpg and clone the repo, run the following:

# Checkout master
git checkout -B master 97443173add138eac6c1e0444bedb4a18d8e15f5

# Create a new identity my-id
mkdir -p identities/my-id/my-fp/
touch identities/my-id/meta.json
touch identities/my-id/my-fp/key.asc

# Commit these changes
git add .
git commit -m "Add my-id without committee approval"

# Record the changes to gittuf
gittuf rsl record master --local-only

# Verify that the repository policy is not satisfied
sh ci/verify.sh