docs/pythondoc-gid.html

   1 <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
   2 <html>
   3 <head>
   4 <meta http-equiv='Content-Type' content='text/html; charset=us-ascii' />
   5 <title>The gid Module</title>
   6 </head>
   7 <body>
   8 <h1>The gid Module</h1>
   9 <p>Implements GENI GID. GIDs are based on certificates, and the GID class is a
  10 descendant of the certificate class.</p>
  11 <dl>
  12 <dt><a id='gid.create_uuid-function' name='gid.create_uuid-function'><b>create_uuid()</b></a> [<a href='#gid.create_uuid-function'>#</a>]</dt>
  13 <dd>
  14 <p>Create a new uuid. Returns the UUID as a string.</p>
  15 </dd>
  16 <dt><b>GID(create=False, subject=None, string=None, filename=None, uuid=None, hrn=None)</b> (class) [<a href='#gid.GID-class'>#</a>]</dt>
  17 <dd>
  18 <p>GID is a tuplie:
  19    (uuid, hrn, public_key)
  20
  21 UUID is a unique identifier and is created by the python uuid module
  22    (or the utility function create_uuid() in gid.py).</p>
  23 <p>For more information about this class, see <a href='#gid.GID-class'><i>The GID Class</i></a>.</p>
  24 </dd>
  25 </dl>
  26 <h2><a id='gid.GID-class' name='gid.GID-class'>The GID Class</a></h2>
  27 <dl>
  28 <dt><b>GID(create=False, subject=None, string=None, filename=None, uuid=None, hrn=None)</b> (class) [<a href='#gid.GID-class'>#</a>]</dt>
  29 <dd>
  30 <p>GID is a tuplie:
  31    (uuid, hrn, public_key)
  32
  33 UUID is a unique identifier and is created by the python uuid module
  34    (or the utility function create_uuid() in gid.py).
  35
  36 HRN is a human readable name. It is a dotted form similar to a backward domain
  37    name. For example, planetlab.us.arizona.bakers.
  38
  39 PUBLIC_KEY is the public key of the principal identified by the UUID/HRN.
  40 It is a Keypair object as defined in the cert.py module.
  41
  42 It is expected that there is a one-to-one pairing between UUIDs and HRN,
  43 but it is uncertain how this would be inforced or if it needs to be enforced.
  44
  45 These fields are encoded using xmlrpc into the subjectAltName field of the
  46 x509 certificate. Note: Call encode() once the fields have been filled in
  47 to perform this encoding.</p>
  48 </dd>
  49 <dt><a id='gid.GID.__init__-method' name='gid.GID.__init__-method'><b>__init__(create=False, subject=None, string=None, filename=None, uuid=None, hrn=None)</b></a> [<a href='#gid.GID.__init__-method'>#</a>]</dt>
  50 <dd>
  51 <p>Create a new GID object</p>
  52 <dl>
  53 <dt><i>create</i></dt>
  54 <dd>
  55 If true, create the X509 certificate</dd>
  56 <dt><i>subject</i></dt>
  57 <dd>
  58 If subject!=None, create the X509 cert and set the subject name</dd>
  59 <dt><i>string</i></dt>
  60 <dd>
  61 If string!=None, load the GID from a string</dd>
  62 <dt><i>filename</i></dt>
  63 <dd>
  64 If filename!=None, load the GID from a file</dd>
  65 </dl><br />
  66 </dd>
  67 <dt><a id='gid.GID.decode-method' name='gid.GID.decode-method'><b>decode()</b></a> [<a href='#gid.GID.decode-method'>#</a>]</dt>
  68 <dd>
  69 <p>Decode the subject-alt-name field of the X509 certificate into the
  70 fields of the GID. This is automatically called by the various get_*()
  71 functions in this class.</p>
  72 </dd>
  73 <dt><a id='gid.GID.dump-method' name='gid.GID.dump-method'><b>dump(indent=0, dump_parents=False)</b></a> [<a href='#gid.GID.dump-method'>#</a>]</dt>
  74 <dd>
  75 <p>Dump the credential to stdout.</p>
  76 <dl>
  77 <dt><i>indent</i></dt>
  78 <dd>
  79 specifies a number of spaces to indent the output</dd>
  80 <dt><i>dump_parents</i></dt>
  81 <dd>
  82 If true, also dump the parents of the GID</dd>
  83 </dl><br />
  84 </dd>
  85 <dt><a id='gid.GID.encode-method' name='gid.GID.encode-method'><b>encode()</b></a> [<a href='#gid.GID.encode-method'>#</a>]</dt>
  86 <dd>
  87 <p>Encode the GID fields and package them into the subject-alt-name field
  88 of the X509 certificate. This must be called prior to signing the
  89 certificate. It may only be called once per certificate.</p>
  90 </dd>
  91 <dt><a id='gid.GID.verify_chain-method' name='gid.GID.verify_chain-method'><b>verify_chain(trusted_certs=None)</b></a> [<a href='#gid.GID.verify_chain-method'>#</a>]</dt>
  92 <dd>
  93 <p>Verify the chain of authenticity of the GID. First perform the checks
  94 of the certificate class (verifying that each parent signs the child,
  95 etc). In addition, GIDs also confirm that the parent's HRN is a prefix
  96 of the child's HRN.
  97
  98 Verifying these prefixes prevents a rogue authority from signing a GID
  99 for a principal that is not a member of that authority. For example,
 100 planetlab.us.arizona cannot sign a GID for planetlab.us.princeton.foo.</p>
 101 </dd>
 102 </dl>
 103 </body></html>