5.17 pisces.spkilib.spki - Core SPKI implementation

5.17 `pisces.spkilib.spki` - Core SPKI implementation

This module implements Python classes that correspond to SPKI object. The objects defined by SPKI are S-expressions consisting of an object name and zero or more ``parts.'' This module defines a Python class for each SPKI object, where the object name corresponds to the class name and the parts correspond to instance attributes.

Each SPKI object is represented in Pisces by a subclass of SPKIObject. These classes have attributes for each of the parts of the S-expression. Some classes also have methods for performing operations using the data contained in the SPKI object; e.g. public-key objects have encrypt and decrypt methods.

SPKIObject ()

This abstract base class defines the sexp method and several operators that rely on the S-expression of an object.

The constructors for SPKIObject instances take a number of argument equal to the number of parts in the S-expression, i.e. the number of parts following the object name.

sexp (): Returns a pisces.spkilib.sexp.SExp for the object.

The following methods use Python operator overloading. They should not be called directly but provide support for Python builtin operations like repr, comparison, and use as a dictionary key.

__repr__ (): Returns the advanced form of the S-expression.

__cmp__ (other): SPKIObject instances are compared using the canonical S-expression encoding.

__hash__ (): The hash of an object is that hash of the canonical encoding of its S-expression.

The object names used by SPKI can not be used directly as Python class names because they contain hyphens. They also clash with typical Python style which uses capital letters. SPKI object names are converted to class names using the name_to_impl function.

name_to_impl (name): Returns the class name corresponding to a SPKI object. Names are translated as follows: The SPKI name is broken up into multiple components at each hyphen. The first letter of each component is capitalized. If the first character of the first component is a number, an underscore is prepended. The SPKI name * is translated as TagExpr.
For example, the SPKI name rsa-pkcs1-md5 is translated as RsaPkcs1Md5.

In some cases, the name returned by name_to_impl refers to a factory function that will produce instances of the desired class. The factory functions are necessary when the class returned depends on some part of the S-expression other than the object name.

There are several helper functions that convert from S-expressions to Python instances.

parse (buf): Parse the canonical S-expression buf and return a SPKIObject instance. Uses pisces.spkilib.sexp.parse.

parseText (s): Parse the human-readable S-expression s and return a SPKIObject instance. Uses pisces.spkilib.sexp.parseText.

Evaluator (*namespaces): An Evaluator instance is used to translate from S-expressions to Python objects. It contains one or more namespaces that map from SPKI object names to factory functions and classes. The optional namespaces arguments must support the mapping protocol.

eval (s, [tag]): Returns a SPKIObject corresponding to the pisces.spkilib.sexp.SExp. It uses an Evaluator intialized with the current module's namespace.

The module defines the following utility functions:

isPrincipal (obj): Return true if obj is a public key or hash.

encryptWithPassword (object, pw[, bogus]): Return a PasswordEncrypted instance containing an encrypted copy of object. The encryption is performed using the PBES2 scheme defined by PKCS #5 using pw as the password, a triple DES in CBC mode as the cipher.
If the optional argument bogus is specified, the object is marked as using a bogus password. This is useful only for testing purposes.

getTime ([t]): Return a time in SPKI format. If t is specified, it must be a numer representing the current Unix time, e.g. as returned by time.time. If t is not specified, the current time is returned.

checkTime (t): Returns true if t is a syntactically valid SPKI time.

getIssuerAndSubject (obj[warning]): Retrieve issuer and subject from obj, which may be a Sequence containing a cert. This function will search through a sequence looking for a cert object or use a cert object passed directly.

extractSignedCert (seq): Extract a cert and its signature from a sequence.

makePublicKey (impl): Return a PublicKey SPKI object from impl, an instance of pisces.pkcs1.RSA_pkcs1. By default, produces an rsa-pkcs1-md5 key.

makePrivateKey (impl): Return a PrivateKey SPKI object from impl, an instance of pisces.pkcs1.RSA_pkcs1. By default, produces an rsa-pkcs1-md5 key.

setHashAlgorithm (alg): Change the hash function used by makePublicKey and makePrivateKey to the algorithm identified by alg, a pisces.asn1.OID.

makeRSAKeyPair (bits): Create a new bits-bit RSA key pair. Return two values, the public and private components. Uses makePublicKey and makePrivateKey.

RSAKeyMaker ([algid])

The functions makePublicKey and makePrivateKey are defined by a default instance of RSAKeyMaker. This class, which is instantiated with the OID of a hash function, generates keys that use that hash function for signing.

makePublicKey (impl): See the function makePublicKey.

makePrivateKey (impl): See the function makePrivateKey.

makeCert (issuer, subject, tag[, propagate[, valid]]): Create a SPKI cert. The issuer and subject must be principals; the function will wrap them in issuer and subject S-expressions. If the propagate keyword arg is true, a propagate entry will be added to the cert. If the valid keyword argument is supplied, it should contain a sequence of validity constraints, e.g. not-before, not-after, and online.

makeNameCert (issuer, subject, name[, valid]): Create a SPKI name cert binding the string name to subject in issuer's namespace. The valid keyword argument should contain one or more validity constraints.

makeAclEntry (subject, valid, propagate, permissions): Return a Entry object for an access control list. An Entry is like a Cert, but without an issuer.

The rest of this section describes the Python classes that correspond to SPKI objects.

Many of the SPKI objects defined in this module do not have methods associated with them. They do define attributes, which are themselves SPKI objects or strings. These objects include Hash, Signature, Do, and Name. Other objects are always contained by another object; e.g. RSAPublicKey is always used as a component of PublicKey. The contained classes are not documented.

PublicKey (key)

The implementation delegates all calls to the contained RSAPublicKey object, which in turn delegates to a pisces.pkcs1.RSA_pkcs1 object.