cleaned up documentation
[sfa.git] / util / hierarchy.py
1 ##
2 # This module implements a hierarchy of authorities and performs a similar
3 # function as the "tree" module of the original geniwrapper prototype. An HRN
4 # is assumed to be a string of authorities separated by dots. For example,
5 # "planetlab.us.arizona.bakers". Each component of the HRN is a different
6 # authority, with the last component being a leaf in the tree.
7 #
8 # Each authority is stored in a subdirectory on the registry. Inside this
9 # subdirectory are several files:
10 #      *.GID - GID file
11 #      *.PKEY - private key file
12 #      *.DBINFO - database info
13 ##
14
15 import os
16 import report
17 from cert import *
18 from credential import *
19 from gid import *
20 from misc import *
21 from config import *
22 from geniticket import *
23
24 ##
25 # The AuthInfo class contains the information for an authority. This information
26 # includes the GID, private key, and database connection information.
27
28 class AuthInfo():
29     hrn = None
30     gid_object = None
31     gid_filename = None
32     privkey_filename = None
33     dbinfo_filename = None
34
35     ##
36     # Initialize and authority object.
37     #
38     # @param hrn the human readable name of the authority
39     # @param gid_filename the filename containing the GID
40     # @param privkey_filename the filename containing the private key
41     # @param dbinfo_filename the filename containing the database info
42
43     def __init__(self, hrn, gid_filename, privkey_filename, dbinfo_filename):
44         self.hrn = hrn
45         self.set_gid_filename(gid_filename)
46         self.privkey_filename = privkey_filename
47         self.dbinfo_filename = dbinfo_filename
48
49     ##
50     # Set the filename of the GID
51     #
52     # @param fn filename of file containing GID
53
54     def set_gid_filename(self, fn):
55         self.gid_filename = fn
56         self.gid_object = None
57
58     ##
59     # Get the GID in the form of a GID object
60
61     def get_gid_object(self):
62         if not self.gid_object:
63             self.gid_object = GID(filename = self.gid_filename)
64         return self.gid_object
65
66     ##
67     # Get the private key in the form of a Keypair object
68
69     def get_pkey_object(self):
70         return Keypair(filename = self.privkey_filename)
71
72     ##
73     # Get the dbinfo in the form of a dictionary
74
75     def get_dbinfo(self):
76         f = file(self.dbinfo_filename)
77         dict = eval(f.read())\r
78         f.close()\r
79         return dict\r
80 \r
81     ##\r
82     # Replace the GID with a new one. The file specified by gid_filename is\r
83     # overwritten with the new GID object\r
84     #\r
85     # @param gid object containing new GID\r
86 \r
87     def update_gid_object(self, gid):\r
88         gid.save_to_file(self.gid_filename)\r
89         self.gid_object = gid\r
90 \r
91 ##\r
92 # The Hierarchy class is responsible for managing the tree of authorities.\r
93 # Each authority is a node in the tree and exists as an AuthInfo object.\r
94 #\r
95 # The tree is stored on disk in a hierarchical manner than reflects the\r
96 # structure of the tree. Each authority is a subdirectory, and each subdirectory\r
97 # contains the GID, pkey, and dbinfo files for that authority (as well as\r
98 # subdirectories for each sub-authority)\r
99
100 class Hierarchy():
101     ##
102     # Create the hierarchy object.
103     #
104     # @param basedir the base directory to store the hierarchy in
105
106     def __init__(self, basedir="."):
107         self.basedir = os.path.join(basedir, "authorities")
108
109     ##
110     # Given a hrn, return the filenames of the GID, private key, and dbinfo
111     # files.
112     #
113     # @param hrn the human readable name of the authority
114
115     def get_auth_filenames(self, hrn):
116         leaf = get_leaf(hrn)
117         parent_hrn = get_authority(hrn)
118         directory = os.path.join(self.basedir, hrn.replace(".", "/"))
119
120         gid_filename = os.path.join(directory, leaf+".gid")
121         privkey_filename = os.path.join(directory, leaf+".pkey")
122         dbinfo_filename = os.path.join(directory, leaf+".dbinfo")
123
124         return (directory, gid_filename, privkey_filename, dbinfo_filename)
125
126     ##
127     # Check to see if an authority exists. An authority exists if it's disk
128     # files exist.
129     #
130     # @param the human readable name of the authority to check
131
132     def auth_exists(self, hrn):
133         (directory, gid_filename, privkey_filename, dbinfo_filename) = \
134             self.get_auth_filenames(hrn)
135
136         return os.path.exists(gid_filename) and \
137                os.path.exists(privkey_filename) and \
138                os.path.exists(dbinfo_filename)
139
140     ##
141     # Create an authority. A private key for the authority and the associated
142     # GID are created and signed by the parent authority.
143     #
144     # @param hrn the human readable name of the authority to create
145     # @param create_parents if true, also create the parents if they do not exist
146
147     def create_auth(self, hrn, create_parents=False):
148         report.trace("Hierarchy: creating authority: " + hrn)
149
150         # create the parent authority if necessary
151         parent_hrn = get_authority(hrn)
152         if (parent_hrn) and (not self.auth_exists(parent_hrn)) and (create_parents):
153             self.create_auth(parent_hrn, create_parents)
154
155         (directory, gid_filename, privkey_filename, dbinfo_filename) = \
156             self.get_auth_filenames(hrn)
157
158         # create the directory to hold the files
159         try:
160             os.makedirs(directory)\r
161         # if the path already exists then pass\r
162         except OSError, (errno, strerr):\r
163             if errno == 17:\r
164                 pass
165
166         pkey = Keypair(create = True)
167         pkey.save_to_file(privkey_filename)
168
169         gid = self.create_gid(hrn, create_uuid(), pkey)
170         gid.save_to_file(gid_filename, save_parents=True)
171
172         # XXX TODO: think up a better way for the dbinfo to work
173
174         dbinfo = get_default_dbinfo()
175         dbinfo_file = file(dbinfo_filename, "w")
176         dbinfo_file.write(str(dbinfo))\r
177         dbinfo_file.close()
178
179     ##
180     # Return the AuthInfo object for the specified authority. If the authority
181     # does not exist, then an exception is thrown. As a side effect, disk files
182     # and a subdirectory may be created to store the authority.
183     #
184     # @param hrn the human readable name of the authority to create.
185
186     def get_auth_info(self, hrn):
187         #report.trace("Hierarchy: getting authority: " + hrn)
188
189         if not self.auth_exists(hrn):
190             raise MissingAuthority(hrn)
191
192         (directory, gid_filename, privkey_filename, dbinfo_filename) = \
193             self.get_auth_filenames(hrn)
194
195         auth_info = AuthInfo(hrn, gid_filename, privkey_filename, dbinfo_filename)
196
197         # check the GID and see if it needs to be refreshed
198         gid = auth_info.get_gid_object()
199         gid_refreshed = self.refresh_gid(gid)
200         if gid != gid_refreshed:
201             auth_info.update_gid_object(gid_refreshed)
202
203         return auth_info
204
205     ##
206     # Create a new GID. The GID will be signed by the authority that is it's
207     # immediate parent in the hierarchy (and recursively, the parents' GID
208     # will be signed by its parent)
209     #
210     # @param hrn the human readable name to store in the GID
211     # @param uuid the unique identifier to store in the GID
212     # @param pkey the public key to store in the GID
213
214     def create_gid(self, hrn, uuid, pkey):
215         gid = GID(subject=hrn, uuid=uuid, hrn=hrn)
216
217         parent_hrn = get_authority(hrn)
218         if not parent_hrn:
219             # if there is no parent hrn, then it must be self-signed. this
220             # is where we terminate the recursion
221             gid.set_issuer(pkey, hrn)
222         else:
223             # we need the parent's private key in order to sign this GID
224             parent_auth_info = self.get_auth_info(parent_hrn)
225             gid.set_issuer(parent_auth_info.get_pkey_object(), parent_auth_info.hrn)
226             gid.set_parent(parent_auth_info.get_gid_object())
227
228         gid.set_pubkey(pkey)
229         gid.encode()
230         gid.sign()
231
232         return gid
233
234     ##
235     # Refresh a GID. The primary use of this function is to refresh the
236     # the expiration time of the GID. It may also be used to change the HRN,
237     # UUID, or Public key of the GID.
238     #
239     # @param gid the GID to refresh
240     # @param hrn if !=None, change the hrn
241     # @param uuid if !=None, change the uuid
242     # @param pubkey if !=None, change the public key
243
244     def refresh_gid(self, gid, hrn=None, uuid=None, pubkey=None):
245         # TODO: compute expiration time of GID, refresh it if necessary
246         gid_is_expired = False
247
248         # update the gid if we need to
249         if gid_is_expired or hrn or uuid or pubkey:
250             if not hrn:
251                 hrn = gid.get_hrn()
252             if not uuid:
253                 uuid = gid.get_uuid()
254             if not pubkey:
255                 pubkey = gid.get_pubkey()
256
257             gid = self.create_gid(hrn, uuid, pubkey)
258
259         return gid
260
261     ##
262     # Retrieve an authority credential for an authority. The authority
263     # credential will contain the authority privilege and will be signed by
264     # the authority's parent.
265     #
266     # @param hrn the human readable name of the authority
267
268     def get_auth_cred(self, hrn):
269         auth_info = self.get_auth_info(hrn)
270         gid = auth_info.get_gid_object()
271
272         cred = Credential(subject=hrn)
273         cred.set_gid_caller(gid)
274         cred.set_gid_object(gid)
275         cred.set_privileges("authority")
276         cred.set_delegate(True)
277         cred.set_pubkey(auth_info.get_gid_object().get_pubkey())
278
279         parent_hrn = get_authority(hrn)
280         if not parent_hrn:
281             # if there is no parent hrn, then it must be self-signed. this
282             # is where we terminate the recursion
283             cred.set_issuer(auth_info.get_pkey_object(), hrn)
284         else:
285             # we need the parent's private key in order to sign this GID
286             parent_auth_info = self.get_auth_info(parent_hrn)
287             cred.set_issuer(parent_auth_info.get_pkey_object(), parent_auth_info.hrn)
288             cred.set_parent(self.get_auth_cred(parent_hrn))
289
290         cred.encode()
291         cred.sign()
292
293         return cred
294     ##
295     # Retrieve an authority ticket. An authority ticket is not actually a
296     # redeemable ticket, but only serves the purpose of being included as the
297     # parent of another ticket, in order to provide a chain of authentication
298     # for a ticket.
299     #
300     # This looks almost the same as get_auth_cred, but works for tickets
301     # XXX does similarity imply there should be more code re-use?
302     #
303     # @param hrn the human readable name of the authority
304
305     def get_auth_ticket(self, hrn):
306         auth_info = self.get_auth_info(hrn)
307         gid = auth_info.get_gid_object()
308
309         ticket = Ticket(subject=hrn)
310         ticket.set_gid_caller(gid)
311         ticket.set_gid_object(gid)
312         ticket.set_delegate(True)
313         ticket.set_pubkey(auth_info.get_gid_object().get_pubkey())
314
315         parent_hrn = get_authority(hrn)
316         if not parent_hrn:
317             # if there is no parent hrn, then it must be self-signed. this
318             # is where we terminate the recursion
319             ticket.set_issuer(auth_info.get_pkey_object(), hrn)
320         else:
321             # we need the parent's private key in order to sign this GID
322             parent_auth_info = self.get_auth_info(parent_hrn)
323             ticket.set_issuer(parent_auth_info.get_pkey_object(), parent_auth_info.hrn)
324             ticket.set_parent(self.get_auth_cred(parent_hrn))
325
326         ticket.encode()
327         ticket.sign()
328
329         return ticket
330