Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Motivation #13

Open
wants to merge 16 commits into
base: master
Choose a base branch
from
Open

Motivation #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
40d9fa2
added ODCA use case
May 10, 2019
238bcc0
clean up language
May 10, 2019
82b2180
clean up language
May 10, 2019
69bb926
adding version to DID method
twshelton May 12, 2019
0d91d35
adding initial terminology section
twshelton May 12, 2019
facdd7f
adding version to DID method
twshelton May 12, 2019
e2d3afb
adding initial terminology section
twshelton May 12, 2019
e41d60e
added status of diddir code
May 13, 2019
5e9fd31
Merge pull request #15 from dhuseby/readme
dhuseby May 13, 2019
611baa3
Merge pull request #14 from twshelton/master
dhuseby May 16, 2019
ad26157
fixing formatting to be text editor friendly
May 16, 2019
f0a69b2
Merge pull request #19 from dhuseby/spec
dhuseby May 16, 2019
27cf0d2
added ODCA use case
May 10, 2019
276b3b6
clean up language
May 10, 2019
27d9906
clean up language
May 10, 2019
4c7f7d9
fixed issue
Jun 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,6 @@ each area.
## BetterSign TODO:

- [x] Create a public [repo for BetterSign signing tool](https://github.com/dhuseby/bs).
- [ ] Upload existing code.
- [ ] Upload existing bs code.
- [x] Create a public [repo for the DIDDir library](https://github.com/dhuseby/diddir).
- [x] Upload existing diddir code.
162 changes: 131 additions & 31 deletions did-git-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,50 +1,124 @@
Note: for everything marked (Optional),
Note: for everything marked (Optional),

# Git DID Method 1.0

# Abstract
# Abstract

Git is a revision control system designed to enable contributors to collaborate in a distributed fashion with no centralized repository. Git supports digitally signing changes with GPG/GPGSM but it is of limited utility because of the lack of widespread adoption of GPG and the infrastructure for key escrowing. This document defines the [DID Method](https://w3c-ccg.github.io/did-spec/#specific-did-method-schemes) for using a Git repository as a source of truth about the repository and its contributors.
Git is a revision control system designed to enable contributors to collaborate
in a distributed fashion with no centralized repository. Git supports digitally
signing changes with GPG/GPGSM but it is of limited utility because of the lack
of widespread adoption of GPG and the infrastructure for key escrowing. This
document defines the [DID
Method](https://w3c-ccg.github.io/did-spec/#specific-did-method-schemes) for
using a Git repository as a source of truth about the repository and its
contributors.

# Introduction

The Git revision control tool is designed to function in a decentralized peer-to-peer fashion to facilitate collaboration in the frequently-disconnected world. Git uses a directed acyclic graph (DAG) of commits that represent the changes to the folders and files in the repository. Because it uses blockchain-like hash-linking of commits, Git is an effective tool for tracking the provenance of data inside the repository. Git also records the author and other meta data such as digital signatures with each commit linking identity of committers to each commit. Git repos therefore contain all of the information needed to serve as the single source of truth for the provenance of the data it contains and the identities of the contributors that created it.
The Git revision control tool is designed to function in a decentralized
peer-to-peer fashion to facilitate collaboration in the frequently-disconnected
world. Git uses a directed acyclic graph (DAG) of commits that represent the
changes to the folders and files in the repository. Because it uses
blockchain-like hash-linking of commits, Git is an effective tool for tracking
the provenance of data inside the repository. Git also records the author and
other meta data such as digital signatures with each commit linking identity of
committers to each commit. Git repos therefore contain all of the information
needed to serve as the single source of truth for the provenance of the data it
contains and the identities of the contributors that created it.

## Motivation

### Developer Certificate of Origin Compliance

The Linux Foundation requires that all contributions to their open source projects are made by individuals that assert that their contribution adheres to the terms of the [Developer Certificate of Origin](https://developercertificate.org/). The contributor signals their assertion by using either Git's [`--signoff`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff) feature, [digital signature](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) feature, or both when committing their changes.
The Linux Foundation requires that all contributions to their open source
projects are made by individuals that assert that their contribution adheres to
the terms of the [Developer Certificate of
Origin](https://developercertificate.org/). The contributor signals their
assertion by using either Git's
[`--signoff`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff)
feature, [digital
signature](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) feature,
or both when committing their changes.

### Data Interoperability Standards Management

The Overlay Data Capture Architecture aims to be a universal tool for data interoperability. It provides for composable multi-dimensional schemas which can be dynamically linked to allow for data pooling and frictionless data sharing. In the case of multiple parties wanting to work together to create standard schemas for a particular use case (an industry consortium standardizing product labels, for instance) but who don't necessarily trust one another, this method provides the ability to enforce a governance framework for managing a shared repository while not giving any one entity the keys to the castle.


### Verifiable Claims Against Open Source Contributions

### Authorship and Intellectual Property Rights

## Terminology

- **Commit ID**

A Git commit ID is a checksum (SHA1 hash) of every important aspect of a commit
including

1. The contents of the commit
2. Commit date
3. Committer's name and email address
4. Log message
5. The ID of the previous commit(s)

[A more detailed
description](https://git-scm.com/book/en/v1/Getting-Started-Git-Basics#Git-Has-Integrity)

- **Repo ID**

The Repo ID is the Commit ID of the commit adding this file into the repository
and can be found in the `did/repo.did` file.

- **Contributor ID**

The Contributor ID is a hash of the Contributor's Public Key from the DID
document that they control and can be found in the `did/<Contributor ID>.did`
file.

TODO:
- [ ] Is this hash = Base64(SHA256(PublicKey from DID Document))?



### Shared Overlay Repositories

The Overlay Data Capture Architecture aims to be a universal tool for data interoperability. It provides for multi-dimensional schemas which can be dynamically linked to allow for efficient data pooling. In case multiple parties want to work together to create standard schemas for a particular use case (an industry consortium standardizing product labels, for instance) but don't necessarily trust one another, this method provides the ability to enforce a governance framework for managing a shared repository while not giving any one entity the keys to the castle.

# Git DID Method

The namestring that shall identify this DID method is `:git`.

A DID that uses this method MUST begin with the following prefix: `did:git`. Per the DID specification, this string MUST be in lowercase. The remainder of the DID, after the prefix, is the NSI specified below.
A DID that uses this method MUST begin with the following prefix: `did:git`.
Per the DID specification, this string MUST be in lowercase. The remainder of
the DID, after the prefix, is the NSI specified below.

# Target System(s)

This DID method applies to Git beginning with the release of Git that supports the DID signing tool.
This DID method applies to Git beginning with the release of Git that supports
the DID signing tool.

# Namespace Specific Identifier (NSI)

The `:git` namestring is defined by the following [ABNF](ftp://ftp.rfc-editor.org/in-notes/std/std68.txt):
The `:git` namestring is defined by the following
[ABNF](ftp://ftp.rfc-editor.org/in-notes/std/std68.txt):

```abnf
git-did = "did:git:commitid" 1*(":" keyid) 1*(";" did-service) 1*("/" did-path) 1*("?" did-query) 1*("#" did-fragment)
commitid = 40*(lowerhex)
keyid = 64*(lowerhex)
lowerhex = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7"
lowerhex = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7"
/ "8" / "9" / "a" / "b" / "c" / "d" / "e" / "f"
```

All Git DIDs consist of one lower case hexidecimal string that is the commit ID for the commit that added the `repo.did` document for the repo and an optional lower case hexidecimal string that is the SHA-256 hash of the public key associated with a DID document stored in the repo itself.
All Git DIDs consist of one lower case hexidecimal string that is the commit ID
for the commit that added the `repo.did` document for the repo and an optional
lower case hexidecimal string that is the SHA-256 hash of the public key
associated with a DID document stored in the repo itself.

The commit ID portion becomes a globally unique identifier for the Git repository and is immutable for the life of the Git repository. The "constitution" file contains the list of key IDs of the maintainers
The commit ID portion becomes a globally unique identifier for the Git
repository and is immutable for the life of the Git repository. The
"constitution" file contains the list of key IDs of the maintainers

# (Optional) JSON-LD Context Definition

Expand All @@ -54,13 +128,17 @@ The commit ID portion becomes a globally unique identifier for the Git repositor

# CRUD Operations

## Create
## Create

**1. Repository DID**

The operation of creating a git-did can be done at any point in a git repository.

A DID Document should be created at `did/repo.did` and all maintainer DID documents added into the did/ directory. All files are then signed and committed by one of the associated keys in the authentication block into the project. The SHA1 of the commit is then used to create the git-did for this respository.
A DID Document should be created at `did/repo.did` and all maintainer DID
documents added into the did/ directory. All files are then signed and
committed by one of the associated keys in the authentication block into the
project. The SHA1 of the commit is then used to create the git-did for this
respository.

For example:

Expand Down Expand Up @@ -99,13 +177,14 @@ Example:
```
**2. Contributor DID**

To create a Contributor DID, add public DID document into the did/ directory and name it using a `<author key id>.did`
To create a Contributor DID, add public DID document into the did/ directory
and name it using a `<author key id>.did`

An example DID doc is shown below.
```jsonld
{
"@context": "https://wsid.org/git-method/v1",
"id": "did:git:<commit SHA1>:<author key id>",
"id": "did:git:<commit SHA1>:<author key id>",
"publicKey": [{
"id": "did:git:<commit SHA1>:<author key id>",
"type": "<signature type>",
Expand All @@ -117,50 +196,71 @@ Example:
```jsonld
{
"@context": "https://wsid.org/git-method/v1",
"id": "did:git:abcde12345/hijklmn678919",
"id": "did:git:abcde12345/hijklmn678919",
"publicKey": [{
"id": "did:git:abcde12345/hijklmn678919",
"type": "ED25519SignatureVerification",
"publicKeyBase58": "..."
}
}
```
The commit adding your DID document should be signed by the key associated private key of the public key referenced in the DID document.
The commit adding your DID document should be signed by the key associated
private key of the public key referenced in the DID document.

## Read

Notes: since we don't know the repo did string when the repo DID document is created, the repo DID document will not contain the "id" did string for the repo. The `git did read` operation will "resolve" the "id" by looking up the SHA1 hash of the commit that added the DID document to the repo and dynamically add the "id" member to what is rendered to the user.
Notes: since we don't know the repo did string when the repo DID document is
created, the repo DID document will not contain the "id" did string for the
repo. The `git did read` operation will "resolve" the "id" by looking up the
SHA1 hash of the commit that added the DID document to the repo and dynamically
add the "id" member to what is rendered to the user.

## Update
## Update
**1. Repository DID**

There aren't currently any keys associated with the respository, so there will ne no need to update the Public Keys in the DID document. The process to change the maintainers or the canonical endpoint should be defined in the `did/governance.md` file.
There aren't currently any keys associated with the respository, so there will
ne no need to update the Public Keys in the DID document. The process to
change the maintainers or the canonical endpoint should be defined in the
`did/governance.md` file.

**2. Contributor DID**

To update a Contributor DID document, update the current DID document in the repository and rename the file to reflect the new public key. Once all changes have been made commit and sign with the private key of the DID document before it was changed.
To update a Contributor DID document, update the current DID document in the
repository and rename the file to reflect the new public key. Once all changes
have been made commit and sign with the private key of the DID document before
it was changed.

## Delete (Revoke)

**1. Repository DID**

The DID for the repository can be deleted by removing the `did/repo.did` file from the respository and performaing a commit. The signature of this commit should correspond to one of the maintainers in the `did/repo.did#authentication list.

The DID for the repository can be deleted by removing the `did/repo.did` file
from the respository and performaing a commit. The signature of this commit
should correspond to one of the maintainers in the `did/repo.did#authentication
list.

**2. Contributor DID**

Deletion of a personal did will remove the file from `did/<author key id>.did`. The `<author did key>.did` is maintained in history which supports provability. The signature over this change should correspond to one of the maintainers in the `did/repo.did#authentication list or the private key of the associated DID document itself.

Deletion of a personal did will remove the file from `did/<author key id>.did`.
The `<author did key>.did` is maintained in history which supports provability.
The signature over this change should correspond to one of the maintainers in
the `did/repo.did#authentication list or the private key of the associated DID
document itself.
TODO:
- What happens when re-established? (confirm: new repo.did = new commit hash = new did?)
- Is this how we give first-class status to branches/forks - e.g. fork/branch, delete repo.did, re-create new repo.did in each relevant position
- [ ] What happens when re-established? (confirm: new repo.did = new commit hash = new did?)
- [ ] Is this how we give first-class status to branches/forks - e.g. fork/branch, delete repo.did, re-create new repo.did in each relevant position

# Security Considerations

This spec applies only to versions of git >= 2.13.0, which used hardened SHA-1. Versions less than v.2.13.0 are susceptible to a [critical hash collision vulnerability](https://github.com/git/git/blob/master/Documentation/technical/hash-function-transition.txt), and MUST NOT be used for implementing this method.
This spec applies only to versions of git >= 2.13.0, which used hardened SHA-1.
Versions less than v.2.13.0 are susceptible to a [critical hash collision
vulnerability](https://github.com/git/git/blob/master/Documentation/technical/hash-function-transition.txt),
and MUST NOT be used for implementing this method.

# Privacy Considerations

Since DIDs can be resolved by anyone, care should be taken to ensure the DID Document does not contain any sensitive personal information.
Since DIDs can be resolved by anyone, care should be taken to ensure the DID
Document does not contain any sensitive personal information.

# Reference Implementations

Expand All @@ -187,5 +287,5 @@ Since DIDs can be resolved by anyone, care should be taken to ensure the DID Doc
- roll -> used to indicate maintainer/contributor status

# Resources
The Peer DID Method Spec is very similar in nature and can be used as a reference point.
(https://dhh1128.github.io/peer-did-method-spec/index.html)
The Peer DID Method Spec is very similar in nature and can be used as a
reference point. (https://dhh1128.github.io/peer-did-method-spec/index.html)