Clearinghouseapi2

Clearinghouse API (revision 2, draft)

Revision 2 of the Clearinghouse is unstable, and subject to further change. The most recent stable revision is numbered 1.

The Clearing House presents the standard ProtoGENI XMLRPC interface to clients.

GetCredential

Request a credential for accessing certain protected parts of the clearinghouse API.

string GetCredential();

Returns a credential suitable for accessing the clearinghouse (a "self certificate"). No arguments are provided. Authorization is implicit in that only a ProtoGeni Authority (Slice Authority, Component Manager) that is already known to the clearinghouse (part of the federation) may request a credential.

The credential is returned as an XML document adhering to the schema in credential.rnc. Specifically, the target_gid of the credential is the clearinghouse GID and the owner_gid is the GID of the requesting entity (inherent in the SSL certificate used to authenticate). Thus, the credential can only be used at the clearinghouse and only by the requester.

Availability: supported in revisions 0 to 2.

Register

int Register(credential, gid, info);

where credential is the credential returned by the GetCredential() call above, and gid is the certificate (public key) of the object to be registered. The info argument is an array of additional arguments specific to the principal being registered. The return value is success or failure.

The GID, being an X.509 certificate, will include a subjectAltName extension with a uniformResourceIdentifier corresponding to the URN of the principal it represents.

When the URN identifies an authority, then info must contain the rest of the details needed to register the principal:

{
  "url"  : "URL of the XML-RPC server",
}

When the object is a user, additional information must be provided:

{
  "email" : "registered email address",
  "name"  : "common name",
}

When the object is a slice:

{
  "creator" : "URN of the slice creator",
}

Slice authorities register the slices they create, as well as the users who create those slices. SAs and CMs are registered with the clearinghouse as part of the process of joining the federation. Component Managers (will, but do not yet) register the components they manage.

Availability: supported in revision 2 only. Revisions 0 and 1 supported a Register operation with slightly different semantics.

Resolve

Lookup a URN and return information about the corresponding object:

struct Resolve(credential, urn);

where credential is the credential returned by the GetCredential() call above, and urn is the URN of the object to be resolved.

The return value is an XML document representing a structure. For each type of object, a slightly different structure is returned. It should be noted that some of the return values are redundant; they exist inside the certificate, but for user convenience are also returned as separate items. When the object is a slice:

{
  "urn"          : "Uniform Resource Name (URN) of the slice",
  "creator"      : "URN of the slice creator",
  "gid"          : "ProtoGENI Identifier (an X.509 certificate)",
}

When the object is a user:

{
  "uid"  : "login (Emulab) ID of the user.",
  "urn"  : "Uniform Resource Name (URN)",
  "email": "registered email address",
  "gid"  : "ProtoGENI Identifier (an X.509 certificate)",
  "name" : "common name",
}

When the object is an authority (component manager, slice authority, or slice embedding service), or a component:

{
  "urn"  : "Uniform Resource Name (URN)",
  "gid"  : "ProtoGENI Identifier (an X.509 certificate)",
  "url"  : "URL of the XML-RPC server",
}

Availability: supported in revision 2 only. Revisions 0 and 1 supported a Resolve operation with slightly different semantics.

Remove

Remove a principal object from the clearing house database.

int Remove(credential, urn);

where credential is the credential returned by the GetCredential() call above, and urn is the URN of the object to be removed.

The return value is success or failure. Note that only users and slices my be deleted from the clearinghouse at this time.

Availability: supported in revision 2 only. Revisions 0 and 1 supported a Resolve operation with slightly different semantics.

Shutdown

Perform an emergency shutdown on a slice. This is typically invoked by the Slice Authority for the slice, but may be invoked by anyone with a clearinghouse credential (this needs to change to allow anyone with a valid slice credential). As it stands, anyone with a slice credential can contact the Slice Authority for the slice, and ask it to do the shutown operation.

Since the Clearinghouse must contact each Component Manager to tell it to shutdown the slice, this call will return immediately. There is currently no facility to find out if/when the shutdown has completed.

int Shutdown(credential, urn);

where credential is the credential returned by the GetCredential() call above, urn is the URN of the slice to be shutdown.

The return value is success or failure.

Availability: supported in revision 2 only. Revisions 0 and 1 supported a Shutdown operation with slightly different semantics.

ListComponents

Return a list of all component managers. This is typically used by a client to find out where the managers are, so that it can ask the managers about the specific resources it manages.

int ListComponents(credential);

where credential is any valid credential issued by a ProtoGeni authority.

The return value is a list of arrays, where each array contains the gid (certificate) of a component manager. The URN and URL can be extracted from the GID, but as a convenience the array includes these as well.

({
  "gid"  : "ProtoGENI Identifier (an X.509 certificate)",
  "urn"  : "Uniform Resource Name (URN)",
  "url"  : "URL of the XML-RPC server",
 }
 ...
)

Availability: supported in revisions 0 to 2.

PostCRL

This is a !ProtoGENI specific call that is used by the federates to post their Certificate Revocation Lists. The lists are collected and made available as a bundle so that each federate can keep a current list of revoked certificates.

int PostCRL(credential, certificate);

where credential is the credential returned by the GetCredential() call above, and certificate is the CRL.

The return value is success or failure.

The CRL bundle is made available to the federates via http download from the Utah. The federates download a new copy each night, and if it has changed, restarts the apache web server. Since the CRLs are effectively the public certificates, we figure this is a reasonable thing to do.

Availability: supported in revisions 0 to 2.

List

struct[] List(credential,type);

Return a list of all objects of the specified type (which should be one of "Authorities", "Components", "Slices" or "Users"). Upon success, an array of structures is generated, where each structure contains "gid" and "urn" fields corresponding to each available object.

Availability: supported in revisions 0 to 2.

GetVersion

int GetVersion();

Returns an integer corresponding to the revision of this API supported by the clearing house.

Availability: supported in revisions 1 to 2.