From: Scott Baker Date: Wed, 1 Oct 2008 03:06:47 +0000 (+0000) Subject: started API documentation. more to be checked in later X-Git-Tag: sfa-0.9-0@14641~841 X-Git-Url: http://git.onelab.eu/?p=sfa.git;a=commitdiff_plain;h=b0c5d4bb7d0cecaa57f983114edef486038d3644 started API documentation. more to be checked in later --- diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..42ddc10e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,3 @@ +doc: + pythondoc.py ../util/cert.py ../util/credential.py ../util/gid.py ../util/rights.py + \ No newline at end of file diff --git a/docs/README b/docs/README new file mode 100644 index 00000000..3dad1aaf --- /dev/null +++ b/docs/README @@ -0,0 +1,5 @@ +This directory contains API documentation. See the developer's wiki for a +general design overview. + +API documentation is generated by using the pytondoc tool. +See http://effbot.org/zone/pythondoc.htm to obtain the tool. diff --git a/docs/pythondoc-cert.html b/docs/pythondoc-cert.html new file mode 100644 index 00000000..efff287f --- /dev/null +++ b/docs/pythondoc-cert.html @@ -0,0 +1,307 @@ + + + + +The cert Module + + +

The cert Module

+

Geniwrapper uses two crypto libraries: pyOpenSSL and M2Crypto to implement +the necessary crypto functionality. Ideally just one of these libraries +would be used, but unfortunately each of these libraries is independently +lacking. The pyOpenSSL library is missing many necessary functions, and +the M2Crypto library has crashed inside of some of the functions. The +design decision is to use pyOpenSSL whenever possible as it seems more +stable, and only use M2Crypto for those functions that are not possible +in pyOpenSSL. + +This module exports two classes: Keypair and Certificate.

+
+
Certificate(create=False, subject=None, string=None, filename=None) (class) [#]
+
+

The certificate class implements a general purpose X509 certificate, making +use of the appropriate pyOpenSSL or M2Crypto abstractions.

+

For more information about this class, see The Certificate Class.

+
+
Keypair(create=False, string=None, filename=None) (class) [#]
+
+

Public-private key pairs are implemented by the Keypair class.

+

For more information about this class, see The Keypair Class.

+
+
+

The Certificate Class

+
+
Certificate(create=False, subject=None, string=None, filename=None) (class) [#]
+
+

The certificate class implements a general purpose X509 certificate, making +use of the appropriate pyOpenSSL or M2Crypto abstractions. It also adds +several addition features, such as the ability to maintain a chain of +parent certificates, and storage of application-specific data. + +Certificates include the ability to maintain a chain of parents. Each +certificate includes a pointer to it's parent certificate. When loaded +from a file or a string, the parent chain will be automatically loaded. +When saving a certificate to a file or a string, the caller can choose +whether to save the parent certificates as well.

+
+
__init__(create=False, subject=None, string=None, filename=None) [#]
+
+

Create a certificate object.

+
+
create
+
+If create==True, then also create a blank X509 certificate.
+
subject
+
+If subject!=None, then create a blank certificate and set + it's subject name.
+
string
+
+If string!=None, load the certficate from the string.
+
filename
+
+If filename!=None, load the certficiate from the file.
+

+
+
add_extension(name, critical, value) [#]
+
+

Add an X509 extension to the certificate. Add_extension can only be called +once for a particular extension name, due to limitations in the underlying +library.

+
+
name
+
+string containing name of extension
+
value
+
+string containing value of the extension
+

+
+
create() [#]
+
+

Create a blank X509 certificate and store it in this object.

+
+
get_data() [#]
+
+

Return the data string that was previously set with set_data

+
+
get_extension(name) [#]
+
+

Get an X509 extension from the certificate

+
+
get_issuer(which="CN") [#]
+
+

Get the issuer name

+
+
get_parent() [#]
+
+

Return the certificate object of the parent of this certificate.

+
+
get_pubkey() [#]
+
+

Get the public key of the certificate. +It is returned in the form of a Keypair object.

+
+
get_subject(which="CN") [#]
+
+

Get the subject name of the certificate

+
+
is_pubkey(pkey) [#]
+
+

Return True if pkey is identical to the public key that is contained in the certificate.

+
+
pkey
+
+Keypair object
+

+
+
is_signed_by_cert(cert) [#]
+
+

Given a certificate cert, verify that this certificate was signed by the +public key contained in cert. Throw an exception otherwise.

+
+
cert
+
+certificate object
+

+
+
load_from_file(filename) [#]
+
+

Load the certificate from a file

+
+
load_from_pyopenssl_x509(x509) [#]
+
+

Given a pyOpenSSL X509 object, store that object inside of this +certificate object.

+
+
load_from_string(string) [#]
+
+

Load the certificate from a string

+
+
save_to_file(filename, save_parents=False) [#]
+
+

Save the certificate to a file.

+
+
save_parents
+
+If save_parents==True, then also save the parent certificates.
+

+
+
save_to_string(save_parents=False) [#]
+
+

Save the certificate to a string.

+
+
save_parents
+
+If save_parents==True, then also save the parent certificates.
+

+
+
set_data(str) [#]
+
+

Set_data is a wrapper around add_extension. It stores the parameter str in +the X509 subject_alt_name extension. Set_data can only be called once, due +to limitations in the underlying library.

+
+
set_issuer(key, subject=None, cert=None) [#]
+
+

Sets the issuer private key and name

+
+
key
+
+Keypair object containing the private key of the issuer
+
subject
+
+String containing the name of the issuer
+
cert
+
+(optional) Certificate object containing the name of the issuer
+

+
+
set_parent(p) [#]
+
+

Set the parent certficiate.

+
+
p
+
+certificate object.
+

+
+
set_pubkey(key) [#]
+
+

Get the public key of the certificate.

+
+
key
+
+Keypair object containing the public key
+

+
+
set_subject(name) [#]
+
+

Set the subject name of the certificate

+
+
sign() [#]
+
+

Sign the certificate using the issuer private key and issuer subject previous set with set_issuer().

+
+
verify(pkey) [#]
+
+

Verify the authenticity of a certificate.

+
+
pkey
+
+is a Keypair object representing a public key. If Pkey + did not sign the certificate, then an exception will be thrown.
+

+
+
verify_chain(trusted_certs=None) [#]
+
+

Verification examines a chain of certificates to ensure that each parent +signs the child, and that some certificate in the chain is signed by a +trusted certificate. + +Verification is a basic recursion: 

+    if this_certificate was signed by trusted_certs:
+        return
+    else
+        return verify_chain(parent, trusted_certs)
+
+ +At each recursion, the parent is tested to ensure that it did sign the +child. If a parent did not sign a child, then an exception is thrown. If +the bottom of the recursion is reached and the certificate does not match +a trusted root, then an exception is thrown. + +

+
Trusted_certs
+
+is a list of certificates that are trusted.
+

+
+
+

The Keypair Class

+
+
Keypair(create=False, string=None, filename=None) (class) [#]
+
+

Public-private key pairs are implemented by the Keypair class. +A Keypair object may represent both a public and private key pair, or it +may represent only a public key (this usage is consistent with OpenSSL).

+
+
__init__(create=False, string=None, filename=None) [#]
+
+

Creates a Keypair object

+
+
create
+
+If create==True, creates a new public/private key and + stores it in the object
+
string
+
+If string!=None, load the keypair from the string (PEM)
+
filename
+
+If filename!=None, load the keypair from the file
+

+
+
as_pem() [#]
+
+

Return the private key in PEM format.

+
+
create() [#]
+
+

Create a RSA public/private key pair and store it inside the keypair object

+
+
get_m2_pkey() [#]
+
+

Return an OpenSSL pkey object

+
+
get_openssl_pkey() [#]
+
+

Given another Keypair object, return TRUE if the two keys are the same.

+
+
load_from_file(filename) [#]
+
+

Load the private key from a file. Implicity the private key includes the public key.

+
+
load_from_string(string) [#]
+
+

Load the private key from a string. Implicitly the private key includes the public key.

+
+
load_pubkey_from_file(filename) [#]
+
+

Load the public key from a string. No private key is loaded.

+
+
load_pubkey_from_string(string) [#]
+
+

Load the public key from a string. No private key is loaded.

+
+
save_to_file(filename) [#]
+
+

Save the private key to a file

+
+
filename
+
+name of file to store the keypair in
+

+
+
+ diff --git a/docs/pythondoc-credential.html b/docs/pythondoc-credential.html new file mode 100644 index 00000000..4db30397 --- /dev/null +++ b/docs/pythondoc-credential.html @@ -0,0 +1,157 @@ + + + + +The credential Module + + +

The credential Module

+

Implements Geni Credentials + +Credentials are layered on top of certificates, and are essentially a +certificate that stores a tuple of parameters.

+
+
Credential(create=False, subject=None, string=None, filename=None) (class) [#]
+
+

Credential is a tuple: + (GIDCaller, GIDObject, LifeTime, Privileges, Delegate) + +These fields are encoded using xmlrpc into the subjectAltName field of the +x509 certificate.

+

For more information about this class, see The Credential Class.

+
+
+

The Credential Class

+
+
Credential(create=False, subject=None, string=None, filename=None) (class) [#]
+
+

Credential is a tuple: + (GIDCaller, GIDObject, LifeTime, Privileges, Delegate) + +These fields are encoded using xmlrpc into the subjectAltName field of the +x509 certificate. Note: Call encode() once the fields have been filled in +to perform this encoding.

+
+
__init__(create=False, subject=None, string=None, filename=None) [#]
+
+

Create a Credential object

+
+
create
+
+If true, create a blank x509 certificate
+
subject
+
+If subject!=None, create an x509 cert with the subject name
+
string
+
+If string!=None, load the credential from the string
+
filename
+
+If filename!=None, load the credential from the file
+

+
+
can_perform(op_name) [#]
+
+

determine whether the credential allows a particular operation to be +performed

+
+
op_name
+
+string specifying name of operation ("lookup", "update", etc)
+

+
+
decode() [#]
+
+

Retrieve the attributes of the credential from the alt-subject-name field +of the X509 certificate. This is automatically done by the various +get_* methods of this class and should not need to be called explicitly.

+
+
dump(dump_parents=False) [#]
+
+

Dump the contents of a credential to stdout in human-readable format

+
+
dump_parents
+
+If true, also dump the parent certificates
+

+
+
encode() [#]
+
+

Encode the attributes of the credential into a string and store that +string in the alt-subject-name field of the X509 object. This should be +done immediately before signing the credential.

+
+
get_delegate() [#]
+
+

get the delegate bit

+
+
get_gid_caller() [#]
+
+

get the GID of the object

+
+
get_gid_object() [#]
+
+

get the GID of the object

+
+
get_lifetime() [#]
+
+

get the lifetime of the credential

+
+
get_privileges() [#]
+
+

return the privileges as a RightList object

+
+
set_delegate(delegate) [#]
+
+

set the delegate bit

+
+
delegate
+
+boolean (True or False)
+

+
+
set_gid_caller(gid) [#]
+
+

set the GID of the caller

+
+
gid
+
+GID object of the caller
+

+
+
set_gid_object(gid) [#]
+
+

set the GID of the object

+
+
gid
+
+GID object of the object
+

+
+
set_lifetime(lifeTime) [#]
+
+

set the lifetime of this credential

+
+
lifetime
+
+lifetime of credential
+

+
+
set_privileges(privs) [#]
+
+

set the privileges

+
+
privs
+
+either a comma-separated list of privileges of a RightList object
+

+
+
verify_chain(trusted_certs=None) [#]
+
+

Verify that a chain of credentials is valid (see cert.py:verify). In +addition to the checks for ordinary certificates, verification also +ensures that the delegate bit was set by each parent in the chain. If +a delegate bit was not set, then an exception is thrown.

+
+
+ diff --git a/docs/pythondoc-gid.html b/docs/pythondoc-gid.html new file mode 100644 index 00000000..c05dac43 --- /dev/null +++ b/docs/pythondoc-gid.html @@ -0,0 +1,103 @@ + + + + +The gid Module + + +

The gid Module

+

Implements GENI GID. GIDs are based on certificates, and the GID class is a +descendant of the certificate class.

+
+
create_uuid() [#]
+
+

Create a new uuid. Returns the UUID as a string.

+
+
GID(create=False, subject=None, string=None, filename=None, uuid=None, hrn=None) (class) [#]
+
+

GID is a tuplie: + (uuid, hrn, public_key) + +UUID is a unique identifier and is created by the python uuid module + (or the utility function create_uuid() in gid.py).

+

For more information about this class, see The GID Class.

+
+
+

The GID Class

+
+
GID(create=False, subject=None, string=None, filename=None, uuid=None, hrn=None) (class) [#]
+
+

GID is a tuplie: + (uuid, hrn, public_key) + +UUID is a unique identifier and is created by the python uuid module + (or the utility function create_uuid() in gid.py). + +HRN is a human readable name. It is a dotted form similar to a backward domain + name. For example, planetlab.us.arizona.bakers. + +PUBLIC_KEY is the public key of the principal identified by the UUID/HRN. +It is a Keypair object as defined in the cert.py module. + +It is expected that there is a one-to-one pairing between UUIDs and HRN, +but it is uncertain how this would be inforced or if it needs to be enforced. + +These fields are encoded using xmlrpc into the subjectAltName field of the +x509 certificate. Note: Call encode() once the fields have been filled in +to perform this encoding.

+
+
__init__(create=False, subject=None, string=None, filename=None, uuid=None, hrn=None) [#]
+
+

Create a new GID object

+
+
create
+
+If true, create the X509 certificate
+
subject
+
+If subject!=None, create the X509 cert and set the subject name
+
string
+
+If string!=None, load the GID from a string
+
filename
+
+If filename!=None, load the GID from a file
+

+
+
decode() [#]
+
+

Decode the subject-alt-name field of the X509 certificate into the +fields of the GID. This is automatically called by the various get_*() +functions in this class.

+
+
dump(indent=0, dump_parents=False) [#]
+
+

Dump the credential to stdout.

+
+
indent
+
+specifies a number of spaces to indent the output
+
dump_parents
+
+If true, also dump the parents of the GID
+

+
+
encode() [#]
+
+

Encode the GID fields and package them into the subject-alt-name field +of the X509 certificate. This must be called prior to signing the +certificate. It may only be called once per certificate.

+
+
verify_chain(trusted_certs=None) [#]
+
+

Verify the chain of authenticity of the GID. First perform the checks +of the certificate class (verifying that each parent signs the child, +etc). In addition, GIDs also confirm that the parent's HRN is a prefix +of the child's HRN. + +Verifying these prefixes prevents a rogue authority from signing a GID +for a principal that is not a member of that authority. For example, +planetlab.us.arizona cannot sign a GID for planetlab.us.princeton.foo.

+
+
+ diff --git a/docs/pythondoc-rights.html b/docs/pythondoc-rights.html new file mode 100644 index 00000000..cc32deea --- /dev/null +++ b/docs/pythondoc-rights.html @@ -0,0 +1,111 @@ + + + + +The rights Module + + +

The rights Module

+

This Module implements rights and lists of rights for the Geni wrapper. Rights +are implemented by two classes: + +Right - represents a single right + +RightList - represents a list of rights + +A right may allow several different operations. For example, the "info" right +allows "listslices", "listcomponentresources", etc.

+
+
privilege_table (variable) [#]
+
+

privilege_table is a list of priviliges and what operations are allowed +per privilege.

+
+
Right(kind) (class) [#]
+
+

The Right class represents a single privilege.

+

For more information about this class, see The Right Class.

+
+
RightList(string=None) (class) [#]
+
+

A RightList object represents a list of privileges.

+

For more information about this class, see The RightList Class.

+
+
+

The Right Class

+
+
Right(kind) (class) [#]
+
+

The Right class represents a single privilege.

+
+
can_perform(op_name) [#]
+
+

Test to see if this right object is allowed to perform an operation. +Returns True if the operation is allowed, False otherwise.

+
+
op_name
+
+is a string naming the operation. For example "listslices".
+

+
+
is_superset(child) [#]
+
+

Test to see if this right is a superset of a child right. A right is a +superset if every operating that is allowed by the child is also allowed +by this object.

+
+
child
+
+is a Right object describing the child right
+

+
+
+

The RightList Class

+
+
RightList(string=None) (class) [#]
+
+

A RightList object represents a list of privileges.

+
+
add(right) [#]
+
+

Add a right to this list

+
+
right
+
+is either a Right object or a string describing the right
+

+
+
can_perform(op_name) [#]
+
+

Check to see if some right in this list allows an operation. This is +done by evaluating the can_perform function of each operation in the +list.

+
+
op_name
+
+is an operation to check, for example "listslices"
+

+
+
is_superset(child) [#]
+
+

Check to see if all of the rights in this rightlist are a superset +of all the rights in a child rightlist. A rightlist is a superset +if there is no operation in the child rightlist that cannot be +performed in the parent rightlist.

+
+
child
+
+is a rightlist object describing the child
+

+
+
load_from_string(string) [#]
+
+

Load the rightlist object from a string

+
+
save_to_string() [#]
+
+

Save the rightlist object to a string. It is saved in the format of a +comma-separated list.

+
+
+