honor -i and -o as advertised
[sfa.git] / 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>