5.13 pisces.spkilib.database - Store keys and certificates in text file

5.13 `pisces.spkilib.database` - Store keys and certificates in text file

This module defines a format for storing S-expressions in a text file. The file contains one or more base64-encoded S-expressions. Comment lines begin with a #. The classes defined all include a human-readable description of the S-expression in a comment before the actual encoded object. Each type of database defines some specific semantics for the object.

AbstractDatabase (path)

The AbstractDatabase class is the parent of all the specific database types. It implements two general methods and requires that subclasses implement three other that describe the specific kind of S-expressions that are supported.

The constructor argument path specifies the file that contains the database.

The two general methods are:

reload ([create]): Load the contents of the database file into memory. If the optional create argument is non-zero, succeed if the file does not exist; otherwise, an IOError will be raised if the file does not exist.

rewrite (): Save the current contents of the database into the database file.

The methods that must be implemented by subclasses are:

loadObject (obj): Called for each S-expression in the file when reload is executed.

getObjects (): Called by rewrite. This method should return a list of all objects to be written out.

writeStorageHint (obj, io): Called for each S-expression to be written out by rewrite. A hint for S-expression obj should be written to the file-like object io.

DebugDatabase (path)

This method loads in an arbitrary database, but is not capable of rewriting it. It is useful for debugging a database.

ACL (path[, create])

This class defines a file containing pisces.spkilib.spki.Entry objects. Each Entry is written with two hints: the subject and the tag.

This class defines the following additional methods:

add (entry): Add a new Entry object to the database.

lookup (subject): Return all Entry objects that match subject.

CertificateDatabase (path[, create])

This class defines a file containing pisces.spkilib.spki.Cert objects, including name certs. Each cert is written with two hints: the subject and issuer.

This class defines the following additional methods:

lookupBySubject (subject): Return all certs that match subject.

lookupByIssuer (issuer): Return all certs that match issuer.

add (cert): Add a new cert cert to the database.

delete (obj): Delete all certificates with issuer and subject fields that match obj.

PrincipalDatabase (path[, create])

A PrincipalDatabase stores public keys.

This class defines the following additional methods:

add (key): Add the public key key.

lookup (p): Return the key corresponding to hash p.

delete (p): Delete a public key. Accepts a single argument p that can be either a key or its hash.

PrivateKeyDatabase (path[, create])

This class stores private keys. Unlike other database classes, it depends on the order of the objects in the database file being preserved. It stores a collection of private keys and their associated public keys. One of the keys is marked as the default key.

This class defines the following additional methods:

lookup (hash): Return a private key for the principal hash. The hash is of the public part of the key pair.

setDefault (hash): Make the private key for the principal hash the default key.

getDefault (): Return the hash of the public part of the default key.

add (pub, priv): Add the key pair with public part pub and private part priv to the database.

listPublicKeys (): Return a list of all the public keys.

listPrivateKeys (): Return a list of all the private keys.