Changing NetBuild's GPG Trust Parameters

1. Overview.  NetBuild library packages are cryptographically signed by GNU Privacy Guard (gpg) in order to give NetBuild users some protection against alteration of the package from the time that the library is packaged until the time it is installed on the user's system by a NetBuild client. Before a NetBuild client (such as nb) will link to a library, it verifies the library's gpg signature. The signature must be valid (i.e. it must be consistent with the contents of the package), and the key used to sign the package must be considered trustworthy by gpg, before the client will use the library.

When a NetBuild client invokes gpg for the purpose of package signature verification, it tells gpg to use a special set of gpg configuration files (public keys and trust parameters) that are specific to NetBuild. That way, NetBuild's gpg keys and trust parameters are kept separate from the user's normal gpg keys and trust parameters. These files are installed whenever the user types nb -setup.

By default, NetBuild trusts any package that is signed by someone whose key is signed by the key netbuild-master@netlib.org. Essentially what this means is that by default, you are trusting the NetBuild developers to keep the netbuild-master@netlib.org private key safe, and also that you trust the NetBuild developers to not sign the key of any individual who will not keep his private key safe, or who will sign packages without reasonable care.

You may wish to change these parameters. Perhaps you do not trust everyone whom we trust, or perhaps you wish to extend trust to individuals whose keys are not signed by netbuild-master@netlib.org. This document explains how to use gpg to change NetBuild clients' trust parameters.

2. How gpg decides whether to trust a key.   In order for gpg to consider a key trustworthy, one of two conditions must be met: Either:

For example, NetBuild's default gpg parameters (the ones you get when you type "nb -setup") are set up to think (for the purpose of NetBuild signature verification only) that "you" are netbuild-user@cs.utk.edu. netbuild-user@cs.utk.edu is set up as a trusted introducer, and netbuild-user@cs.utk.edu has also signed the key for netbuild-master@netlib.org.

3. How to change gpg's trust parameters.  The files that gpg uses to verify NetBuild packages are kept in $HOME/NetBuild/gnupg. To change NetBuild's gpg trust parameters, use 

gpg --homedir $HOME/NetBuild/gnupg command...
where command is a gpg command to manipulate keys. For instance, 
gpg --homedir $HOME/NetBuild/gnupg --list-sigs
will list all NetBuild keys known to gpg along with their signatures.

4. Creating your own gpg key.  If you wish to change NetBuild's gpg trust parameters you will almost certainly need to create your own gpg key for use with NetBuild signature verification. This is because you do not have the password for netbuild-user@cs.utk.edu's secret key, and you will not be able to sign anyone else's keys without that password.

To create your own gpg key, type 

gpg --homedir $HOME/NetBuild/gnupg --gen-key
You should see something that looks like: 
Please select what kind of key you want:
   (1) DSA and ElGamal (default)
   (2) DSA (sign only)
   (5) RSA (sign only)
Your selection?
RSA keys (selection 5) are recommended for NetBuild. A keysize of 1024 bits is probably adquate. Use 2048 bits if you want more strength, but remember that a chain is only as strong as its weakest length. If someone can break into your computer and steal your keystrokes as you type a password and/or change the gpg binary so that it compromises your key, it doesn't matter how many bits there are in your key. You should name your key with a valid email address to ensure uniqueness.

(We recommend that you DO NOT use this key for signing NetBuild packages, but use it only for signature verification. It may seem odd that you need to create a key that is only used for signature verification, but gpg assumes that every key that is considered trustworthy must be traceable to a key that is signed by you - or at least, it's much easier to configure gpg to work that way.)

5. Revoking trust in the netbuild-master key.  Once you have created your own key, you may wish to revoke trust in the netbuild-master key. Note that if you do this you will not be able to use any of the NetBuild libraries that we supply; you will either have to produce your own libraries, use someone else's libraries, or independently establish trust in individual library signers' keys. If you wish to do this anyway, type: 

gpg --homedir $HOME/NetBuild/gnupg/ --edit-key netbuild-master@netlib.org
At the Command> prompt, type "trust". By default, the trust in this key is "I trust fully" (4). You may wish to change this to "I do NOT trust" (2). Once you have changed this, be sure to type "save" to commit the changes. Then type quit.

On the other hand, if you wish to continue to trust the libraries that we supply, see "Renewing trust in the netbuild-master key" below.

6. Getting rid of the netbuild-user key.  Once you have created your own key you should probably get rid of the netbuild-user@cs.utk.edu key so that gpg will not try to use that key to sign any other keys. Type 

gpg --homedir $HOME/NetBuild/gnupg/ --delete-keys netbuild-user@cs.utk.edu
gpg --homedir $HOME/NetBuild/gnupg/ --delete-secret-keys netbuild-user@cs.utk.edu

7. Signing other keys.  If you wish to sign someone else's NetBuild gpg key (which in turn allows them to sign packages that your NetBuild client will trust) they must first send you a copy of their public key. To get this, they type 

gpg --export their-key-id >filename.gpg
and send filename.gpg to you via email or some other means. (Note that this assumes that the gpg key they use to sign packages is NOT stored in their NetBuild key ring - it should be in their normal GPG key ring).

You then type 

gpg --homedir $HOME/NetBuild/gnupg --import filename.gpg
to incorporate their key in your NetBuild keyring.

Next you must sign the key. Type 

gpg --homedir $HOME/NetBuild/gnupg --sign-key their-key-id
you will be prompted for the password that goes with the private key you created.

Finally, if you wish to allow this person to extend your trust to other keys (so that your NetBuild client will trust any package that they sign) you need to edit that key's trust parameters. Type 

gpg --homedir $HOME/NetBuild/gnupg --edit-key their-key-id
And use the trust subcommand to set trust to "I trust fully" (4). Don't forget to save the new key parameters before typing quit.

8. Renewing trust in the netbuild-master key.  If you wish to continue to trust the netbuild-master key, you should sign it with your new key. Type 

gpg --homedir $HOME/NetBuild/gnupg --sign-key netbuild-master@netlib.org
to sign the key, and 
gpg --homedir $HOME/NetBuild/gnupg --edit-key netbuild-master@netlib.org
to edit the key's trust parameters, following the same pattern as above.
Last Change: 17 May 2004