Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/zyga/distrust


https://github.com/zyga/distrust

Last synced: 2 days ago
JSON representation

Awesome Lists containing this project

README 

        
Distrust - Distributed Trust

============================



Distrust is an experiment in implementing distributed trust system for software

authentication. The intent is to allow users to trust certain developers to

distribute certain software and prevent man-in-the-middle attacks, rogue

releases and compromised download servers.



Distrust is not a new idea, it is, essentially, what some people have been

doing all along, manually checking that a source tarball is properly signed by

a person they trust to release it.



All that distrust does is to take that idea and formalize it so that any user

can benefit and be more secure than they currently are. As an additional

feature the Distrust system allows one to have a meaningful transition from the

mostly-unsigned world to the mostly-signed world (see UNSIGNED SOFTWARE below).



The trust model

===============



Distrust models its trust network after GPG (Gnu Privacy Guard) with some

notable exceptions and extensions.



This document does not explain GPG in any way, you are encouraged to read the

Gnu Privacy Handbook: http://www.gnupg.org/gph/en/manual.html.



The basic concept is that a given user (ISSUER) chooses to trust another user

(SUBJECT) to author some named piece of software (SCOPE).



The distrust system is designed with digital software distribution in mind and

as such it wants to be practically applicable to current environments. As such

it deals with both signed and unsigned software. In both cases the user has the

same level of security, based on trust. Unsigned software is simply more

annoying to trust in practice.



The trust model is distributed because each trust record is signed by the

issuer and can be exchanged with other users. In the same way someone can be a

trusted author of software he might be a trusted reviewer (so I trust the

software he trusts). In both cases control is exclusively in the hands of the

user, there is no implicit trust.



SIGNED SOFTWARE

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



This is the preferred mode. Here the user expresses trust to a particular

person (as identified by their GPG key signature) to author and release

particular software.



The trust system builds upon GPG for known peer identification (so it's good

to know the developer of the software, verify their identify and sign their

public key) but extends it to specify how the trust should be interpreted

(after all, GPG only provides secure authentication, not trust in the action

of the identified person)



Distrust requires working GPG implementation. In all examples below we assume

that all participants already use GPG and have valid keys. More importantly we

do NOT assume that all users exchanged their public keys.



UNSIGNED SOFTWARE

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



This mode is based on cryptographic hashes that are trusted by the user

themselves, and do not require the software distributor to sign. Those are

more annoying as each single unique file needs to be explicitly trusted,

preferably after a manual inspection.



Tutorial

========



Let's look at a first example. The user Alice starts using distrust.



    $ distrust init

    [distrust] Creating trust database in ~/.config/distrust/trust.json



This is basically the clean slate, Alice does not trust anyone yet. It is

important to distinguish the trust Alice chose to put in GPG keys from the

trust she puts in particular people to author software. Those are explicitly

separate.



    $ distrust list

    [distrust] Listing all trust records signed by "Alice User "

    [distrust] There are no trust records yet



Now Alice wants to install a program that her friend Bob wrote, "useful-tool".

Alice already has his public key in her GPG keyring so that part of the problem

is out of the way.



The way the distrust system works, Alice needs to create a trust record that

names Bob as trusted to sign releases of the "useful-tool" program. Since there

is no global naming scheme, Alice needs to namespace the program to a

particular distribution channel. Here Alice will use the "pypi" namespace.



The point of using namespaces is to allow the distrust system to be used by all

developers and downstream consumers (users or developers) regardless of the

language or technology that a particular program is associated with. If

successful, Distrust could be deployed to secure pypi, ruby gems, ubuntu ppa

packages, freedesktop.org source releases and anything else.



Now, going back to the example, Alice will trust Bob to author "useful-tool"



    $ distrust trust person "Bob Developer " with project "pypi:useful-tool"

    [distrust] Looking up "Bob Developer "

    [distrust] Found 1 personality:

    [distrust] pub   2048R/FA519244 2013-02-03 [expires: 2015-02-03]

    [distrust] uid                  Bob Developer 

    [distrust] sub   2048R/A63BAB03 2013-02-03 [expires: 2015-02-03]

    [distrust] Are you sure you want to trust:

    [distrust] "Bob Developer " with project "pypi:useful-tool"?

    [distrust] [yes or no] > yes

    [distrust] Creating signed trust record...

    // GPG invoked to sign the record

    [distrust] Adding trust record to the database...

    [disturst] Done



Now Alice's database contains a record containing precisely that information.

Using it she can download the program from any website or mirror and install it

knowing it came from Bob.



    Note: in the future distrust will be integrated into pip and setuptools

    directly so that all downloaded files have to be trusted and can be

    properly verified.



Alice can proceed to verify the tarball she has:



    $ distrust check "usefull-tool-0.1.tar.gz" with "useful-tool-0.1.tar.gz.asc" for project "pypi:useful-tool"

    [distrust] Checking signature... ok

    [distrust] Checking signer... ok

    [distrust] Checking trust for scope... ok



    Note: It might make some sense to create a new format that encapsulates those three pieces

    of information: the scope, the signature and the payload. Perhaps an ar record, like Debian?



    $ ar t usefull-tool-0.1.dti



Core Commands

=============



There are just two core commands, trust and check. They have two forms each,

one for each signed and unsigned software.



trust person ... for project ...

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



The syntax is:



    $ distrust [--remove|--revoke] trust person  for project 



This is the mode for trusting SIGNED SOFTWARE.



This interactively creates a trust record that allows a given person to

issue releases of the specified project.



The optional --revoke keyword can be used to revoke the trust and create an

explicit distrust record. The user can also provide an optional comment.



The optional --remove keyword can be used to remove a trust record without

creating additional revocation records. This is useful for mistakes where no

breach of trust had occurred and the person is still trustworthy.



This command requires access to the GPG keyring to discover and confirm the

identify of the person and to sign the trust record.



trust file for project

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



The syntax is:



    $ distrust [--remove|--revoke] trust file  for project 



This is the mode for trusting UNSIGNED SOFTWARE.



This interactively creates a trust record that allows anyone to distribute

that particular file which is a part of the the specified project.



This mode allows the user to use the trust system with existing, unsigned

software before the upstream chooses to adopt software signing policy.

The trust is based on a computed, selected cryptographic checksum of the

specified file. The trust records explicitly stores that checksum.



This command requires access to the GPG keyring to sign the trust record.



check ... with signature ... for project ...

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



The syntax is:



    $ distrust check  with  for project 



This non-interactively verifies the trust on a specified file, with the

specified signature file for a particular project. The return code can

be used to discover the failure reason. This command should be used

by external tools to verify downloads. The error codes are documented:



    0 - success.



    This is only returned when a valid signature, created by known issuer,

    was previously trusted by the user for the specified scope.



    1 - invalid signature



    The signature is not valid for the specified file, no further checking

    is provided.



    2 - unknown signer



    The signature is valid but the person signing the file is not known



    3 - no trust record



    The signature is valid, the person is known but there is no trust in that

    person for the specified scope.



The "check" command has a second mode that is suitable for UNSIGNED SOFTWARE.



The syntax is similar:



    $ distrust check  for project 



The only difference is that the signature part is missing. The return codes

in this case are either 0 (success) or 3 (no trust record).



Auxiliary commands

==================



init

----



The syntax is:



    $ distrust init



This initializes the trust system and keeps a persistent database of trust

records in a platform-specific directory specific to the currently running

user.



list

----



The syntax is:



    $ distrust list [--issuer=] [--subject=] [--scope=]



    TBD



publish

-------



The syntax is:



    TBD



    Publishes trust records to a server



import

------



The syntax is:



    TBD



    Imports trust records from a server



trust peer

----------



The syntax is:



    TBD



{Creating,removing,revoking} trust records for peer users (I trust that

$PERSON trust records as I would have if I created them myself)