Project Python SourceForge
Legal Notes
How to
Key Generation
Signing a Document
Testing a Document
Trust Relationships

Trust Relationships

Trust relationships are, admittedly, fairly tricky. Fortunately, you don't generally need to use them.

Let's pretend that our current keyset was created by an application's programmer. Graham has hard-coded his public key into the application so it will read any TrustedPickles he might later create. Let's further pretend that another programmer creates a TrustedPickle document to work with Graham's application.

If Graham has written his application in a flexible manner, it will alert users when they try to load this new document. It could then give them the option to use the document anyhow and even allow future documents signed by this new programmer.

This is all well and fine, but a stern warning will discourage wide-scale adoption of this new document. Let's say that Graham wants to accept all documents from this new programmer. He now has three options:

  1. Re-sign this (and all future) documents with his own key.
  2. Hard-code this new public key into the application as well and release a new version of the application.
  3. Sign a trust relationship with the new programmer.

Obviously the first two options are less desirable.

To demonstrate how this works, we're going to need a second set of keys to represent the second programmer. In the real world, this new programmer would create his/er own keys, so Graham would never have access to his/er private key.

>>> TrustedPickle.NewKeys()
Your name: Terry Gilliam
Your e-mail address:
Key pair filename base ( & ___.prv): terry
Private key password (blank OK): ("Brazil" not shown)
Repeat password (for verification): ("Brazil" not shown)

Now we need to do some file shuffling. Terry needs to get his public key file over to Graham so that he can create the trust relationship. Graham is providing proof that he trusts Terry, so he signs with his private key.

Note: Public key files may be freely shared. They do not contain any sensative data.

>>> PubKeyFile.AddTrust("", PrivKey)
>>> PubKeyFile.Write()

This may be confusing, but the new trust relationship that Graham just signed is written into Graham's public key file, and not Terry's. Graham could update Terry's public key file and then mail it back to him, but then Terry would have to trust that Graham has not erased any previous trust relationships out of the file (or otherwise corrupted the file). I know I wouldn't be comfortable doing that, so let's not assume that Terry is either.

Instead, let's have Graham mail his new public key file over to Terry so Terry can use it to update his own public key file. This can be done with the Merge() function.

>>> PubKeyFile2 = TrustedPickle.PublicKeyFile("")
>>> PubKeyFile2.Read()
>>> PubKeyFile2.Merge("")
>>> PubKeyFile2.Write()

Now that Terry has a public key file showing that Graham trusts him, let's create a new document file and have Terry sign it.

>>> PrivKey2 = TrustedPickle.PrivateKey("terry.prv", "Brazil")
>>> PrivKey2.Read()
>>> Doc2 = TrustedPickle.TPickle("terry.tpk")
>>> Doc2.Pickle("Terry's document is this string.")
>>> Doc2.Sign(PubKeyFile2, PrivKey2, True)
>>> Doc2.Write()

Note the extra parameter when we called the Sign() function this time. This indicates to include all upstream trust relationships in the document.

Now let's test the document against Graham's public key.

>>> SigClass, SigList = Doc2.TestSignatures(Trusted)
>>> SigClass == TrustedPickle.TRANSFERRED
>>> len(SigList)
>>> SigList[0].Name
'Graham Chapman'

The signature class code is now TRANSFERRED. Note that although Terry actually signed the document, Graham's public key is returned by TestSignatures(). Graham is the trusted user and he vouched for Terry's opinion.