docs/pythondoc-hierarchy.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 hierarchy Module</title>
   6 </head>
   7 <body>
   8 <h1>The hierarchy Module</h1>
   9 <p>This module implements a hierarchy of authorities and performs a similar
  10 function as the &quot;tree&quot; module of the original geniwrapper prototype. An HRN
  11 is assumed to be a string of authorities separated by dots. For example,
  12 &quot;planetlab.us.arizona.bakers&quot;. Each component of the HRN is a different
  13 authority, with the last component being a leaf in the tree.
  14
  15 Each authority is stored in a subdirectory on the registry. Inside this
  16 subdirectory are several files:
  17      *.GID - GID file
  18      *.PKEY - private key file
  19      *.DBINFO - database info</p>
  20 <dl>
  21 <dt><b>AuthInfo(hrn, gid_filename, privkey_filename, dbinfo_filename)</b> (class) [<a href='#hierarchy.AuthInfo-class'>#</a>]</dt>
  22 <dd>
  23 <p>The AuthInfo class contains the information for an authority.</p>
  24 <p>For more information about this class, see <a href='#hierarchy.AuthInfo-class'><i>The AuthInfo Class</i></a>.</p>
  25 </dd>
  26 <dt><b>Hierarchy(basedir=&quot;.&quot;)</b> (class) [<a href='#hierarchy.Hierarchy-class'>#</a>]</dt>
  27 <dd>
  28 <p>The Hierarchy class is responsible for managing the tree of authorities.</p>
  29 <p>For more information about this class, see <a href='#hierarchy.Hierarchy-class'><i>The Hierarchy Class</i></a>.</p>
  30 </dd>
  31 </dl>
  32 <h2><a id='hierarchy.AuthInfo-class' name='hierarchy.AuthInfo-class'>The AuthInfo Class</a></h2>
  33 <dl>
  34 <dt><b>AuthInfo(hrn, gid_filename, privkey_filename, dbinfo_filename)</b> (class) [<a href='#hierarchy.AuthInfo-class'>#</a>]</dt>
  35 <dd>
  36 <p>The AuthInfo class contains the information for an authority. This information
  37 includes the GID, private key, and database connection information.</p>
  38 </dd>
  39 <dt><a id='hierarchy.AuthInfo.__init__-method' name='hierarchy.AuthInfo.__init__-method'><b>__init__(hrn, gid_filename, privkey_filename, dbinfo_filename)</b></a> [<a href='#hierarchy.AuthInfo.__init__-method'>#</a>]</dt>
  40 <dd>
  41 <p>Initialize and authority object.</p>
  42 <dl>
  43 <dt><i>hrn</i></dt>
  44 <dd>
  45 the human readable name of the authority</dd>
  46 <dt><i>gid_filename</i></dt>
  47 <dd>
  48 the filename containing the GID</dd>
  49 <dt><i>privkey_filename</i></dt>
  50 <dd>
  51 the filename containing the private key</dd>
  52 <dt><i>dbinfo_filename</i></dt>
  53 <dd>
  54 the filename containing the database info</dd>
  55 </dl><br />
  56 </dd>
  57 <dt><a id='hierarchy.AuthInfo.get_dbinfo-method' name='hierarchy.AuthInfo.get_dbinfo-method'><b>get_dbinfo()</b></a> [<a href='#hierarchy.AuthInfo.get_dbinfo-method'>#</a>]</dt>
  58 <dd>
  59 <p>Get the dbinfo in the form of a dictionary</p>
  60 </dd>
  61 <dt><a id='hierarchy.AuthInfo.get_gid_object-method' name='hierarchy.AuthInfo.get_gid_object-method'><b>get_gid_object()</b></a> [<a href='#hierarchy.AuthInfo.get_gid_object-method'>#</a>]</dt>
  62 <dd>
  63 <p>Get the GID in the form of a GID object</p>
  64 </dd>
  65 <dt><a id='hierarchy.AuthInfo.get_pkey_object-method' name='hierarchy.AuthInfo.get_pkey_object-method'><b>get_pkey_object()</b></a> [<a href='#hierarchy.AuthInfo.get_pkey_object-method'>#</a>]</dt>
  66 <dd>
  67 <p>Get the private key in the form of a Keypair object</p>
  68 </dd>
  69 <dt><a id='hierarchy.AuthInfo.set_gid_filename-method' name='hierarchy.AuthInfo.set_gid_filename-method'><b>set_gid_filename(fn)</b></a> [<a href='#hierarchy.AuthInfo.set_gid_filename-method'>#</a>]</dt>
  70 <dd>
  71 <p>Set the filename of the GID</p>
  72 <dl>
  73 <dt><i>fn</i></dt>
  74 <dd>
  75 filename of file containing GID</dd>
  76 </dl><br />
  77 </dd>
  78 <dt><a id='hierarchy.AuthInfo.update_gid_object-method' name='hierarchy.AuthInfo.update_gid_object-method'><b>update_gid_object(gid)</b></a> [<a href='#hierarchy.AuthInfo.update_gid_object-method'>#</a>]</dt>
  79 <dd>
  80 <p>Replace the GID with a new one. The file specified by gid_filename is
  81 overwritten with the new GID object</p>
  82 <dl>
  83 <dt><i>gid</i></dt>
  84 <dd>
  85 object containing new GID</dd>
  86 </dl><br />
  87 </dd>
  88 </dl>
  89 <h2><a id='hierarchy.Hierarchy-class' name='hierarchy.Hierarchy-class'>The Hierarchy Class</a></h2>
  90 <dl>
  91 <dt><b>Hierarchy(basedir=&quot;.&quot;)</b> (class) [<a href='#hierarchy.Hierarchy-class'>#</a>]</dt>
  92 <dd>
  93 <p>The Hierarchy class is responsible for managing the tree of authorities.
  94 Each authority is a node in the tree and exists as an AuthInfo object.
  95
  96 The tree is stored on disk in a hierarchical manner than reflects the
  97 structure of the tree. Each authority is a subdirectory, and each subdirectory
  98 contains the GID, pkey, and dbinfo files for that authority (as well as
  99 subdirectories for each sub-authority)</p>
 100 </dd>
 101 <dt><a id='hierarchy.Hierarchy.auth_exists-method' name='hierarchy.Hierarchy.auth_exists-method'><b>auth_exists(hrn)</b></a> [<a href='#hierarchy.Hierarchy.auth_exists-method'>#</a>]</dt>
 102 <dd>
 103 <p>Check to see if an authority exists. An authority exists if it's disk
 104 files exist.</p>
 105 <dl>
 106 <dt><i>the</i></dt>
 107 <dd>
 108 human readable name of the authority to check</dd>
 109 </dl><br />
 110 </dd>
 111 <dt><a id='hierarchy.Hierarchy.create_auth-method' name='hierarchy.Hierarchy.create_auth-method'><b>create_auth(hrn, create_parents=False)</b></a> [<a href='#hierarchy.Hierarchy.create_auth-method'>#</a>]</dt>
 112 <dd>
 113 <p>Create an authority. A private key for the authority and the associated
 114 GID are created and signed by the parent authority.</p>
 115 <dl>
 116 <dt><i>hrn</i></dt>
 117 <dd>
 118 the human readable name of the authority to create</dd>
 119 <dt><i>create_parents</i></dt>
 120 <dd>
 121 if true, also create the parents if they do not exist</dd>
 122 </dl><br />
 123 </dd>
 124 <dt><a id='hierarchy.Hierarchy.create_gid-method' name='hierarchy.Hierarchy.create_gid-method'><b>create_gid(hrn, uuid, pkey)</b></a> [<a href='#hierarchy.Hierarchy.create_gid-method'>#</a>]</dt>
 125 <dd>
 126 <p>Create a new GID. The GID will be signed by the authority that is it's
 127 immediate parent in the hierarchy (and recursively, the parents' GID
 128 will be signed by its parent)</p>
 129 <dl>
 130 <dt><i>hrn</i></dt>
 131 <dd>
 132 the human readable name to store in the GID</dd>
 133 <dt><i>uuid</i></dt>
 134 <dd>
 135 the unique identifier to store in the GID</dd>
 136 <dt><i>pkey</i></dt>
 137 <dd>
 138 the public key to store in the GID</dd>
 139 </dl><br />
 140 </dd>
 141 <dt><a id='hierarchy.Hierarchy.get_auth_cred-method' name='hierarchy.Hierarchy.get_auth_cred-method'><b>get_auth_cred(hrn)</b></a> [<a href='#hierarchy.Hierarchy.get_auth_cred-method'>#</a>]</dt>
 142 <dd>
 143 <p>Retrieve an authority credential for an authority. The authority
 144 credential will contain the authority privilege and will be signed by
 145 the authority's parent.</p>
 146 <dl>
 147 <dt><i>hrn</i></dt>
 148 <dd>
 149 the human readable name of the authority</dd>
 150 </dl><br />
 151 </dd>
 152 <dt><a id='hierarchy.Hierarchy.get_auth_filenames-method' name='hierarchy.Hierarchy.get_auth_filenames-method'><b>get_auth_filenames(hrn)</b></a> [<a href='#hierarchy.Hierarchy.get_auth_filenames-method'>#</a>]</dt>
 153 <dd>
 154 <p>Given a hrn, return the filenames of the GID, private key, and dbinfo
 155 files.</p>
 156 <dl>
 157 <dt><i>hrn</i></dt>
 158 <dd>
 159 the human readable name of the authority</dd>
 160 </dl><br />
 161 </dd>
 162 <dt><a id='hierarchy.Hierarchy.get_auth_info-method' name='hierarchy.Hierarchy.get_auth_info-method'><b>get_auth_info(hrn)</b></a> [<a href='#hierarchy.Hierarchy.get_auth_info-method'>#</a>]</dt>
 163 <dd>
 164 <p>Return the AuthInfo object for the specified authority. If the authority
 165 does not exist, then an exception is thrown. As a side effect, disk files
 166 and a subdirectory may be created to store the authority.</p>
 167 <dl>
 168 <dt><i>hrn</i></dt>
 169 <dd>
 170 the human readable name of the authority to create.</dd>
 171 </dl><br />
 172 </dd>
 173 <dt><a id='hierarchy.Hierarchy.get_auth_ticket-method' name='hierarchy.Hierarchy.get_auth_ticket-method'><b>get_auth_ticket(hrn)</b></a> [<a href='#hierarchy.Hierarchy.get_auth_ticket-method'>#</a>]</dt>
 174 <dd>
 175 <p>Retrieve an authority ticket. An authority ticket is not actually a
 176 redeemable ticket, but only serves the purpose of being included as the
 177 parent of another ticket, in order to provide a chain of authentication
 178 for a ticket.
 179
 180 This looks almost the same as get_auth_cred, but works for tickets
 181 XXX does similarity imply there should be more code re-use?</p>
 182 <dl>
 183 <dt><i>hrn</i></dt>
 184 <dd>
 185 the human readable name of the authority</dd>
 186 </dl><br />
 187 </dd>
 188 <dt><a id='hierarchy.Hierarchy.refresh_gid-method' name='hierarchy.Hierarchy.refresh_gid-method'><b>refresh_gid(gid, hrn=None, uuid=None, pubkey=None)</b></a> [<a href='#hierarchy.Hierarchy.refresh_gid-method'>#</a>]</dt>
 189 <dd>
 190 <p>Refresh a GID. The primary use of this function is to refresh the
 191 the expiration time of the GID. It may also be used to change the HRN,
 192 UUID, or Public key of the GID.</p>
 193 <dl>
 194 <dt><i>gid</i></dt>
 195 <dd>
 196 the GID to refresh</dd>
 197 <dt><i>hrn</i></dt>
 198 <dd>
 199 if !=None, change the hrn</dd>
 200 <dt><i>uuid</i></dt>
 201 <dd>
 202 if !=None, change the uuid</dd>
 203 <dt><i>pubkey</i></dt>
 204 <dd>
 205 if !=None, change the public key</dd>
 206 </dl><br />
 207 </dd>
 208 </dl>
 209 </body></html>