Skip to content. | Skip to navigation

Personal tools


You are here: Home / Wiki / Authimpl


Protogeni Authentication, Credentials, Tickets, etc.

Protogeni Authentication, Credentials, Tickets, etc.

High-level Factoids

  • Protogeni employs a "web of trust" model in which all of the members of the federation hold copies of all root keys (trust anchors).
  • Each user has an encrypted SSL certificate issued by their home Emulab that authenticates them to the entire federation, by virtue of the fact that the certificate is signed by one of the federation members (trust anchor).
  • A GID (Geni Identifier) is simply an SSL certificate with a Distinguished Name (DN) field that conforms to a set of conventions. There is also some additional info in the Subject Alternative Name part of the certificate.
  • Interaction with the GMC API is via SSL sessions in which the caller's identity and authentication is their aforementioned certificate (GID).
  • A user's "privileges" are contained within a Protogeni Credential. In other words, their certificate indicates identity, but it is a credential that gives them permission to do something useful within the API.
  • A "Ticket" is simply another kind of credential.
  • A Credential (and a Ticket) is an xml document that has been signed.

Identity and Authentication

Each member of the Protogeni federation is itself an Emulab installation. Part of the installation process for each federate is the generation of a self-signed certificate authority certificate, that serves as the "root" for that Emulab. This root certificate is subsequently used to sign, among other things, the certificates of its users. This certificate becomes their Protogeni identity; it allows them to initiate an SSL session with any of the RPC servers in the federation. Since all of the federates maintain a cache of the root certificates, the signatures can be trivially verified at any federate.

As mentioned above, authentication implies no permission; API operations require a credential, discussed below.

The certificate that is generated for users includes a couple of items that establish the user's GID (Geni Identifier). They are stored in the DN field of the certificate, and include the user's UUID and their Human Readable Name (HRN). Fundamentally, it is the UUID that determines which user; a user may regenerate their certificate, but they will have the same UUID embedded in it. The HRN is included for compatibility with other systems, but within Protogeni it is not used for identification (although it can be used in Resolve() operations). In addition, the DN field also includes the email address for the user.

Users are not the only Protogeni entities with assigned certificates; each of the principle objects in Protogeni has a unique UUID and thus a certificate (GID) associated with it. In most cases these certificates are used for identity purposes, not authentication (as in an SSL session). For example, when constructing a credential for a slice, the target of the credential is the GID for the slice. More on this in the credential section below.


A Protogeni credential is the basis for granting privileges to users. Privileges take the form of a small XML document describing what actions may be taken or applied to a specific Protogeni principle. A "credential" is that bit of XML, signed by some authority (or a chain of authorities) that can verified back to one of the trusted root authorities mentioned above. The current implementation of credentials uses the XML Digital Signatures format, and the XMLSEC library to generate and verify the signed document.

As an example, consider the user Joe who has created a slice nicknamed MySlice. When Joe asks his Slice Authority to create this new slice, a new credential is formed that includes, among other items:

Joe's GID (UUID, HRN, email)
MySlice's GID (UUID, HRN, email)
A list of tokens
A digital signature

Joe's GID is the one that is maintained by his home Emulab. The GID for MySlice is a brand new certificate which includes a new UUID assigned to MySlice. The list of tokens defines what operations (destroy, modify, etc) Joe may take with respect to MySlice. Lastly, a digital signature that covers all of this information. The entire credential, still an xml document, is returned to Joe so it can be used in subsequent operations. The next thing Joe might do is destroy the slice. To do that, Joe will initiate an SSL session with the Slice Authority RPC server, passing the credential to the DeleteSlice() operation. The operation succeeds because the credential is valid (the signature verifies) and Joe is the user in the credential.

Regarding the last statement, the signature verifies because any unauthorized changes would invalidate the digital signature. In addition, only Joe can use this credential because only Joe has the pass phrase to his personal certificate, that he uses to initiate the SSL session with the RPC server. Thus, the certificate (GID) associated with the client of the session is the same as the GID contained in the credential.

Please see the credential specification for more details.


Tickets are a variant of a credential. Instead of a list of tokens, as in a credential, there is an rspec. As with credentials, tickets includes the GID of the user and the GID of the slice to which the ticket refers. Thus, a ticket grants the holder a "promise" to assign the set of resources in the rspec, to the slice that is referenced in the ticket. Once the ticket is redeemed, it is effectively useless in subsequent operations.

Credentials and tickets include an expiration date. This expiration is currently unused in credentials, but is set to a very short time (on the order of minutes) for tickets. Component Managers will not honor a ticket that has expired; a new ticket must be requested, although the same resources may no longer be available.

More details to follow.


Delegation is the ability to sign a credential (or Ticket) over to another user such that the target user can present it and be granted the same (or optionally restricted) permissions of the original user. For example, Joe has a slice credential and wants to sign that credential over to Mary so that she can manipulate the slice. Remember, a credential specifies an owner GID, and when that user authenticates to one of the RPC servers, the GID (certificate) they use to initiate the SSL connection must match the GID in the credential the pass along. In other words, Joe cannot just email his certificate to Mary who then tries to use it; that would be a GID mismatch.

Delegation then, allows Joe to use the private key of his GID to sign his credential over to Mary, as long Joe has Mary's GID (the public part). At the same time, Joe can modify the privileges in the delegated credential, possibly reducing the set of privileges (obviously, Joe cannot grant privileges he himself does not have). Joe can also indicate which of the privileges he passes on, can further be passed on by Mary to another user. For example, Joe can pass the 'delete' privilege to Mary, but specify that Mary cannot pass that privilege to another user.

Okay, enough of Joe and Mary. Lets talk implementation. The credential specification supports delegation by wrapping an existing credential with a new credential, and then adding a signature over the result. So, initially a credential might look like this:

(ID #1
 Joe's GID
 MySlice GID
 [control:1, instantiate:1])
A digital signature over credential #1

This credential says that the owner has "control" and "instantiate" permission over the slice, and that he can delegate those privileges to someone else. The digital signature prevents any modification of the credential, verifiable back to the trusted root certificate of the Slice Authority that granted the credential. To verify this credential, all that needs to be done is verify the signature, and that the public key (included in the signature section) corresponding to the private key that signed the credential, is verifiable back to a trusted root. Since the credential was issued by a trusted root, that is a trivial operation. To delegate this credential, the user would construct a new credential like:

(ID #2
 Mary's GID
 MySlice GID
 (ID #1
  Joe's GID
  MySlice GID
  [control:1, instantiate:1]))
A digital signature over credential #1
A digital signature over credential #2

This new credential allows Mary to instantiate the slice, but not control it. The credential cannot be further delegated since there are no privileges specified with the delegate bit set. The second digital signature covers the new credential (referenceduby ID!#2), which includes the parent credential (referenced by !#1). Thus, the signature is over both the new and the old credential. Since it was Joe who was delegating this credential, it is his certificate (private key) that is used to create the signature (ie: the credential is signed by Joe).

Verifying the delegated credential takes a few extra steps. First the !#2 signature must be verified, and the public key used to create that signature must be verified back to a trusted root. In this case Joe's public key is included in signature !#2, and since it was issued by a trusted root, the signature is valid. The next step is to verify signature !#1 over the credential referenced by ID!#1. If it verifies, then Joe did not try to alter the credential he was issued before delegating it. Next, the sequence of privilege tokens is sanity checked to make sure that only privileges that were marked as being delegatable have been passed along. If this check passes, then the credential is considered valid.

Delegation is operational in sufficiently recent CVS revisions, and is being actively worked on. An example of using the delegation tools is available.


CRLs (Certificate Revocation Lists) are supported by Protogeni. Each member of the federation runs a cron job that generates a CRL once a day, and posts that CRL to the Clearinghouse. The Clearinghouse collects the CRLS and combines them into a single bundle and posts them for all of the federates. The CRLs allow the federates to be notified in a timely manner of users that are no longer allowed to use the Protogeni APIs (say, if a user account is terminated). CRLs also allow users to change their certificates; the old certificate is revoked so that it can no longer be used.