[Blocks-development] Trust Network standards document v0.02

[Michael S. Jr. <m...@ms...>]

This is an early, partial draft of the web-of-trust standards document.  It
doesn't detail enough layers to form a complete web-of-trust yet.

Someone had recommended transferring signatures with the file adverts.  If
that gets implemented, that would replace the bottom layer -- the transport
mechanism for all this crypto material.

Do we need overseas developers now?  We don't want to run afowl of United
States cryptographic technology export restrictions...and we definitely
don't want someone in the US to get the bright idea that...if they merely
classify distributed filesharing technology to be a munition, they could
legally do bad things to the authors of these programs.  :(

Please, please, give me comments, propose changes, and wildly speculate out
loud on the mailing list.  This isn't just 'my baby' -- my vision starts
running a bit thin after about the fourth layer.  This is only a framework.
It's up to you guys to come up with cool and useful ways to use the
framework.

--Michael Spencer
bl...@ms...

-----START OF STANDARDS DOCUMENT-----
BLOCKS NETWORK PUBLIC-KEY CRYPTO SPECIFICATION

Distribution:  unlimited

The current version of this file is:  0.02
If you make a change to this document, please add your changes to the
changelog at the end and increment the version number.  For synchronization,
please email changes, comments, vague ideas, and premonitions to
bl...@ms... to prevent version number conflicts between multiple
authors.  I'll try to make sure everything makes it in.

------------------------------------------------------------------------

The trusted file network is composed of several layers.  The lower (inner)
layers are more concrete and basic things:  a file, a signature, a packet.
The higher (upper) layers are more abstract but meaningful things:
identities, trust, content.

**********

BOTTOM LAYER:  FILES

All Trust Network data exists within files.  Files are cached in a directory
on the local machine, or can be searched for on the Blocks Net.

----------

Filenames:

public key:
pk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

XXXXX == fingerprint of public key, 40 hex digits
obtain fingerprint with:  gpg --fingerprint
add the public key to your keyring with:  type pk-XXXXXXXXXX...XXXX | gpg

key signature:
sig-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY
YYYYYYYYY

XXXXX == fingerprint of public key being signed, 40 hex digits
YYYYY == fingerprint of signing key, 40 hex digits
verify the signature with:  type sig-XXXX...YYY | gpg

content signature (or other message about content):
cs-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ

XXXXX == fingerprint of signing key, 40 hex digits
ZZZZZ == content-hash of file being signed, 32 hex digits
verify the signature with:  type cs-XXXX...ZZZ | gpg

----------

File object descriptions:

public key:
A public key is a piece of cryptographic material, generated by GPG (or
equivalent) and used to verify signatures made on content and on other keys.
You should read and understand how GPG and public-key cryptography works
before continuing.

key signature:
This should be a file which contains a machine-readable statement of trust
about a key ("I certify that the world should trust this key this much"),
which is signed with a GPG signature.

content signature:
This should be a file with a machine-readable statement of trust about
content, which is signed with a GPG signature.  Details about the content of
the key and content signatures will be detailed in a higher layer.

**********

SECOND LAYER:  CRYPTOGRAPHIC MATERIAL

The Trust Network relies upon signatures made with cryptographic material to
validate trust information.  This cryptographic material is currently
created and verified with GPG, but the content of the messages the
cryptographic material validates must be interpreted by hand or with another
program.

This layer doesn't care about what the messages actually mean.  This layer
only creates and validates keys and signatures.

----------

Create a key:

All of these commands should be run from the directory you have GPG
installed in.

1)  Create the public key pair
At the command prompt, type:  gpg --gen-key
When asked for the type of key you want, select 1:  DSA and ElGamal
When asked for a keysize, type in 2048
Tell it Yes, you really need such a large keysize.
Key is valid for: 0 (does not expire)
When asked if this is correct, say Yes.
When asked for a real name, type:  BLOCKS
When asked for an email address, just hit enter
When asked for a comment, type your user name or alias.
(where <username> is your preferred user name, alias, whatever...just like
your user name on Napster would be.)
FIXME:  Should we have some kind of guidelines about the uniqueness of
usernames?  Keys will be selected by Key ID anyway...but the username field
will be the human-readable part of the key.
When asked to confirm, type O for OK.
Enter a pass phrase to protect your secret key -- you will use this pass
phrase whenever you create a signature using that key.
Retype the pass phrase.  If you mistyped the pass phrase, you will need to
retype it again twice.
After you type the pass phrase, a secret key will be created and added to
pubring.gpg and secring.gpg in the current directory.
2)  Export the public key to a file
At the command prompt, type:  gpg --export -a <username> > pubkey.txt
(where <username> is the name, handle, or nick you picked for yourself in
step 1.)
3)  Change the filename to the Blocks standard
At the command prompt, type:  gpg --fingerprint <username>
(where <username> is the name, handle, or nick you picked for yourself in
step 1.)
Note the "Key fingerprint =" line -- you'll need to type those hex digits in
by hand.
At the command prompt, type:  ren pubkey.txt
pk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
(where XXXXXXX matches the Key fingerprint line's contents -- 40 hex digits
with no spaces)
4)  copy your new pk- file to your blocks/trustnet directory.
FIXME:  I just made up blocks/trustnet, analogous to blocks/cache and
blocks/files.  If someone else has a better name in mind, please suggest it.
5)  Upload your pk- file to the network!

----------

Add someone else's key to your keyring:

1)  Find and download the pk- file from Blocks.
2)  Copy the pk- file to your GPG directory
3)  Add the key in the pk- file to your public keyring
At the command prompt, type:  type pk-XXXXX...XXX | gpg
You should see output that lists the key just added, with BLOCKS (username)
on the right.  If you are prompted for your passphrase, or you see any other
strange output, the file you processed wasn't a public key.

----------

Create a signature:

1)  Prepare the file or packet you're going to sign.  Note that for a sig-
or cs- file, the contents of the file you're signing is defined in a higher
layer.  If no higher layers have been defined, just make something up.
2)  Create a cleartext signed file from the original packet.
From the command line, type:  gpg --clearsign --textmode <filename>
When asked for the pass phrase for your secret key, type it in.
GPG will create another file.  If your source file had an extension (like
.txt), the output file will have the original extension removed and .asc
appended.  If the source file did not have an extension, the output file
will have .asc appended.
3)  Change the filename to the Blocks standard
If the file is a signature of another key, use pk-XXXXX-YYYYY (40 X's and 40
Y's).  If the file is a signature of a file, use cs-XXXXX-ZZZZZ (40 X's and
32 Z's).  If the file is some other kind of file (pertaining to a message
board or chat room or something else) use that file type's standard.
4)  Upload the file to the network!

----------

Confirm a signature:

1)  Copy the signed file to your GPG directory.
2)  Verify the signed file
From the command line, type:  gpg filename
If you see:
gpg: Signature made xx/xx/xx xx:xx:xx  using DSA key ID XXXXXXXX
gpg: Good signature from "BLOCKS (username)"
Then you know that key ID XXXXXXXX did indeed sign that file.
If you see:
gpg: Signature made xx/xx/xx xx:xx:xx  using DSA key ID XXXXXXXX
gpg: BAD signature from "BLOCKS (username)"
Then you know the file you're processing has been corrupted or tampered with
in some way.

FIXME: Would it make more sense to use the 8-digit key ID instead of the
40-digit Fingerprint?

**********

This is only the first third of the trust network.  It isn't useful
yet...but people have a chance to practice the procedures and understand the
concepts in the first two layers.  Once we agree on standards for the next
couple layers, we can start creating and trading files.

------------------------------------------------------------------------

Version 0.01:  mspencer  8/2/2000
Created the file name formats, and put very basic directions in about what
to do with the files.

Version 0.02:  mspencer  8/18/2000
Added layer structure, explained the first two layers in detail.  First
public release.
-----END OF STANDARDS DOCUMENT-----