Skip to content

Commit a4ade03

Browse files
shannonashannona
committed
first half of §4.2
1 parent 0fa7cc5 commit a4ade03

2 files changed

Lines changed: 297 additions & 1 deletion

File tree

‎docs/04_2_Publishing_for_Privacy.md‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
# 4.2: Publishing for Privacy
2+
3+
Amira and Ben have a contract that ensures that SisterSpaces will
4+
always be able to use Amira's work. Maybe they're comfortable
5+
publishing that full contract, but maybe they prefer to keep details
6+
to themselves, to maximize the privacy and protection of both
7+
parties. This section explains how they could do so.
8+
9+
> 🧠 **Related Concepts.** After completing this tutorial, explore
10+
[Data Minimization](../concepts/data-minimization.md) and [Elision
11+
Cryptography](../concepts/elision-cryptography.md).
12+
13+
## Objectives of this Section
14+
15+
After working through this section, a developer will be able to:
16+
17+
- Store hashed records of a contract as a commitment.
18+
- Create herd privacy through the publication of numerous hashes.
19+
20+
Supporting objectives include the ability to:
21+
22+
- Understand what a commitment means,
23+
- Understand what herd privacy is.
24+
25+
## Amira's Story: Preserving Privacy
26+
27+
Amira has signed a CLA to allow her work to be used in SisterSpaces'
28+
SecureAuth Library. Most open-source repositories would publish CLAs
29+
like that as part of their repos. But Ben is very aware of privacy
30+
concerns, as many of the women who use his services come from abusive
31+
backgrounds. He extends that to the people working with him.
32+
33+
Because she is standing behind her BRadvoc8 identity, Amira doesn't
34+
have the same concerns as those people working with SisterSpaces
35+
without the benefit of a pseudonymous agreement. In fact, she's eager
36+
to reveal her connection to them to improve the trust for her
37+
identity. But that doesn't mean she wants everyone to know the entire
38+
contents of the contract she signed, or at the least doesn't want the
39+
whole huge text incorporated into her XID.
40+
41+
How can licensing rights be ensured without endangering any of the
42+
participants? The answer is commitments.
43+
44+
## The Power of Commitments
45+
46+
We've seen commitments previously, in
47+
[§2.2](02_2_Managing_Claims_Elision.md). Their use there was simple:
48+
we created a claim; we elided that claim; and then we used the hash of
49+
the claim as proof that the claim existed (and had existed for some
50+
period of time).
51+
52+
At the time we said that the commitment _could_ be published, but we
53+
didn't really say how. This chapter explores that more:
54+
55+
To start with, we offer two major methods to create a commitment:
56+
`shasum` a plain file (which we saw in
57+
[§4.1](04_1_Creating_Binding_Agreements.md)) and `digest` an envelope
58+
(which we use here).
59+
60+
| Hashing Method | App | Section |
61+
|----------------|-----|---------|
62+
| SHASum a File | `shasum` | §4.1 |
63+
| Digest an Envelope | `envelope` | §4.2 |
64+
65+
Each of these digests can also be published in a variety of ways. Ben
66+
incorporated a `shasum` into an envelope in the last section. Here
67+
we're going to see a `digest` incorporated into an envelope and also
68+
discuss how digests can be published in plain (`.md`) files.
69+
70+
| Publication Method | Section |
71+
|--------------------|---------|
72+
| Incorporate into a XID | §4.1, §4.2 |
73+
| In a File | §4.2 |
74+
| As a Long List | §4.2 |
75+
76+
## The Power of Herd Privacy
77+
78+
As noted above, one of the methods of publishing commitments is as
79+
part of a long list. Doing so can create herd privacy. When a long
80+
list of commitments is created, each one blends in with the others. An
81+
observer simply sees a long list of commitments: they can't easily
82+
determine which one belongs to the human rights worker, which to a
83+
student, and which to a retiree. The crowd provides cover.
84+
85+
| Contributors | Observer's Challenge |
86+
|--------------|---------------------|
87+
| 1 | Trivial to identify |
88+
| 10 | Difficult to identify |
89+
| 50 | Needle in haystack |
90+
| 500 | Effectively anonymous |
91+
92+
Even if an attacker discovered a flaw in the methodology that Ben uses
93+
to make commitments, they wouldn't know which hash to try and attack
94+
to prove that BRadvoc8 (or anyone else) is involved. The specifics are lost among the crowd.
95+
96+
## Part 0: Verify Dependencies
97+
98+
Before you get started, you should (as usual) check your `envelope-cli` version:
99+
```
100+
envelope --version
101+
102+
│ bc-envelope-cli 0.34.1
103+
```
104+
105+
Then, reload your XID. We're also going to be using Amira's
106+
attestation key to create a new edge about her work with SisterSpaces,
107+
which will also depend on the CLA she signed.
108+
109+
110+
```
111+
XID=$(cat envelopes/BRadvoc8-xid-private-3-03.envelope)
112+
XID_ID=$(envelope xid id $XID)
113+
PASSWORD="your-password-from-previous-tutorials"
114+
ATTESTATION_PRVKEYS=$(cat envelopes/key-attestation-private-2-01.ur)
115+
CLA=$(cat envelopes/cla-bradvoc8-accepted-4-01.envelope)
116+
```
117+
118+
## Part I: Incorporating a Contract into a XID
119+
120+
Amira is thrilled to talk about her work with SisterSpaces. That's
121+
because Ben's signature on Amira's contract is another step forward in
122+
the progressive trust of BRadvoc8 as a reliable security expert.
123+
124+
On the other hand, she does have some privacy concerns. She knows that
125+
Ben only releases the full CLAs if they're legally necessary to prove
126+
ownership of SisterSpaces code. She wants to respect his privacy and
127+
also doesn't want to clutter up in XID with the full contract.
128+
129+
A commitment of the contract offers a compromise that will meet her
130+
needs to show off the connection but still protect Ben's privacy and
131+
her own XID's accessability.
132+
133+
### Step 1: Create a Contract Edge
134+
135+
To record the contract, Amira will create a new self-attestation edge that
136+
she is working on SisterSpaces.
137+
138+
As with any other edge, she first needs to define the three core elements of the edge: `isA`, `source`, and `target`:
139+
```
140+
ISA="foaf:Project"
141+
SOURCE_XID_ID=$XID_ID
142+
TARGET_XID_ID=$XID_ID
143+
```
144+
145+
To create the commitment of the contract she will use a similar methodology to that of [§2.2](02_2_Managing_Claims_Elision.md).
146+
147+
```
148+
DIGEST_CLA=$(envelope digest "$SIGNED_ACCEPTED_CLA")
149+
```
150+
151+
There, we elided the envelope, leaving only the digest. Here, we're
152+
instead going to incorporate the digest into this claim. If anyone
153+
asks for more info they can ask BRadvoc8 for the full contract, and
154+
she can decide whether it's appropriate to give it out.
155+
156+
The commitment to the conract, as with the rest of the details of the
157+
claim, are placed as a target subenvelope:
158+
159+
```
160+
PROJECT_TARGET=$(envelope subject type ur $TARGET_XID_ID)
161+
PROJECT_TARGET=$(envelope assertion add pred-obj string $ISA string "SisterSpaces" "$PROJECT_TARGET")
162+
PROJECT_TARGET=$(envelope assertion add pred-obj known verifiableAt string "https://github.com/SisterSpaces/SecureAuth/CLAs/" "$PROJECT_TARGET")
163+
PROJECT_TARGET=$(envelope assertion add pred-obj string "claDigest" digest "$DIGEST_CLA" "$PROJECT_TARGET")
164+
```
165+
166+
With those details, you can now put together the contract edge:
167+
168+
```
169+
EDGE=$(envelope subject type string "project-sister-spaces-secureauth")
170+
EDGE=$(envelope assertion add pred-obj known isA string "$ISA" "$EDGE")
171+
EDGE=$(envelope assertion add pred-obj known source ur "$SOURCE_XID_ID" "$EDGE")
172+
EDGE=$(envelope assertion add pred-obj known target envelope "$PROJECT_TARGET" "$EDGE")
173+
174+
echo "SisterSpaces edge details:"
175+
envelope format "$EDGE"
176+
177+
| SisterSpaces edge details:
178+
|
179+
| "project-sister-spaces-secureauth" [
180+
| 'isA': "foaf:Project"
181+
| 'source': XID(5f1c3d9e)
182+
| 'target': XID(5f1c3d9e) [
183+
| "claDigest": Digest(0ecac6b7)
184+
| "foaf:Project": "SisterSpaces"
185+
| 'verifiableAt': "https://github.com/SisterSpaces/SecureAuth/CLAs/"
186+
| ]
187+
| ]
188+
```
189+
190+
This is a relatively simple edge, but that's because the CLA commitment stands in for the entire CLA!
191+
192+
### Step 2: Publish Your Contract Edge
193+
194+
You can now take the several steps to attach this edge and publish the result.
195+
196+
First, incorporate the edge:
197+
```
198+
WRAPPED_EDGE=$(envelope subject type wrapped "$EDGE")
199+
SIGNED_EDGE=$(envelope sign --signer "$ATTESTATION_PRVKEYS" "$WRAPPED_EDGE")
200+
201+
XID_WITH_CONTRACT_EDGE=$(envelope xid edge add \
202+
--verify inception \
203+
$SIGNED_EDGE $XID_WITH_CONTRACT_KEY)
204+
```
205+
206+
Second, advance the provenance mark and produce a public version
207+
```
208+
XID_WITH_CONTRACT_EDGE=$(envelope xid provenance next \
209+
--password "$PASSWORD" \
210+
--sign inception \
211+
--private encrypt \
212+
--generator encrypt \
213+
--encrypt-password "$PASSWORD" \
214+
"$XID_WITH_CONTRACT_EDGE")
215+
PUBLIC_XID_WITH_CONTRACT_EDGE=$(envelope xid export --private elide --generator elide "$XID_WITH_CONTRACT_EDGE")
216+
```
217+
Third, store everything:
218+
219+
```
220+
echo "$PUBLIC_XID_WITH_CONTRACT_EDGE" > envelopes/BRadvoc8-xid-public-4-02.envelope
221+
echo "$XID_WITH_CONTRACT_EDGE" > envelopes/BRadvoc8-xid-private-4-02.envelope
222+
```
223+
You've now demonstrated how Amira highlights her new connection to SisterSpaces while preserving privacy, but that's just half the story.
224+
225+
#### XID Version Comparison
226+
227+
You've now created a sixth XID edition of Amira's XID. Here's another overview of what
228+
each version contains
229+
230+
| XID Version | New Content | Created In |
231+
|-------------|-------------|------------|
232+
| seq 0 | 👤 Identity | §1.2+§1.3 |
233+
| seq 1 | 🔑 Attestation Key | §2.1 |
234+
| seq 2 | 🗣️ GitHub Edge | §3.1 |
235+
| seq 3 | 🗣️ Endorsement Edge | §3.3 |
236+
| seq 4 | 🔑 Contract Key | §3.4 |
237+
| seq 5 | 📄️ Contract scommitment | §3.4 |
238+
239+
## Part II: Incorporating a Contract into a Commitment List
240+
241+
Ben also needs to publish the CLA, to show everyone that his software
242+
is safe to use, because he has contracts with all the authors. But,
243+
Ben has 50 different people who have worked on SisterSpaces (and
244+
signed CLAs). He doesn't want all of that in his XID (or even in a XID
245+
he created for SisterSpaces). Nor does he want to just publish those
246+
CLAs separately, because of the privacy concerns.
247+
248+
His answer: a commitment list
249+
250+
### Step 3: Computer a Digest
251+
252+
[TBD]
253+
254+
### Step 4: Publish a Commitment List
255+
256+
[TBD]
257+
258+
### Step 5: Check a Commitment
259+
260+
[TBD]
261+
262+
## Summary: XXX
263+
264+
...
265+
266+
### Additional Files
267+
268+
**Envelopes:** The
269+
[envelopes](https://github.com/BlockchainCommons/XID-Quickstart/tree/main/envelopes)
270+
directory contains numerous data created in this section, the most
271+
important of which are Amira's sixth
272+
[private](https://github.com/BlockchainCommons/XID-Quickstart/blob/main/envelopes/BRadvoc8-xid-private-4-02.envelope)
273+
and
274+
[public](https://github.com/BlockchainCommons/XID-Quickstart/blob/main/envelopes/BRadvoc8-xid-public-4-02.envelope)
275+
XIDs as well as the
276+
277+
... Ben's list ...
278+
279+
**Scripts:** Scripts demonstrating this section are forthcoming.
280+
281+
### Exercises
282+
283+
...
284+
285+
## What's Next
286+
287+
Though we've completed Amira's first arc, there's one open question: has
288+
her XID gotten too big? [§4.3: Creating Views and
289+
Viewsion](04_3_Creating_Views_and_Versions.md) talks about how to
290+
clean it up.
291+
292+
## Appendix I: Key Terminology
293+
294+
> **Commitment List**:
295+
296+
> **Herd Privacy**:

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
[**Chapter Four: Expanding & Contracting Your XIDs**](04_0_Advanced.md)
2121

2222
* [§4.1: Creating Binding Agreements](04_1_Creating_Binding_Agreements.md)
23-
* [§4.2: Publlshing for Privacy] (**pending**)
23+
* [§4.2: Publlshing for Privacy](04_2_Publishing_for_Privacy.md) (**partial**)
2424
* [§4.3: Creating Views and Versions] (**pending**)
2525

2626
---

0 commit comments

Comments
 (0)