Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Clearinghouseapi1

Clearinghouseapi1

Clearinghouse API (revision 1)

Clearinghouse API (revision 1)

Revision 1 of the Clearinghouse is stable, and not subject to further change. This documentation also describes revision 0, although that version is deprecated.

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 1.

Register

Register a principle object, returning success of failure.

int Register(credential, gid, type, info);

where credential is the credential returned by the GetCredential() call above, gid is the gid (public key) of the object to be registered, and type is one of SA|CM|Component|Slice|User. The info argument is an array of additional arguments specific to the principle being registered. The return value is success or failure.

The GID, being an x509 certificate, will include in its Distinguished Name (DN) and Subject Alternate Name, the rest of the details needed to register the principle:

{
  "hrn"  : "Human Readable Name (HRN)",
  "uuid" : "rfc4122 universally unique identifier",
  "url"  : "URL of the XML-RPC server",
}

When the type is User additional information must be provided:

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

When the type is Slice:

{
  "creator_uuid" : "rfc4122 universally unique identifier 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 revisions 0 to 1.

Resolve

Lookup a UUID and return information about it:

struct Resolve(credential, uuid, type);
struct Resolve(credential, hrn, type);

where credential is the credential returned by the GetCredential() call above, uuid is the uuid of the object to be resolved, and type is one of SA|CM|Component|Slice|User. The second form allows lookup by Human Readable Name (HRN).

The return value is an XML document representing a structure. For each type, 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 type is Slice:

{
  "hrn"          : "Human Readable Name (HRN)",
  "uuid"         : "rfc4122 universally unique identifier",
  "creator_uuid" : "rfc4122 universally unique identifier of slice creator",
  "gid"          : "ProtoGENI Identifier (an x509 certificate)",
}

When the type is User:

{
  "uid"  : "login (Emulab) ID of the user.",
  "hrn"  : "Human Readable Name (HRN)",
  "uuid" : "rfc4122 universally unique identifier",
  "email": "registered email address",
  "gid"  : "ProtoGENI Identifier (an x509 certificate)",
  "name" : "common name",
}

When the type is CM (Component Manager) or SA (Slice Authority) or Component:

{
  "hrn"  : "Human Readable Name (HRN)",
  "uuid" : "rfc4122 universally unique identifier",
  "gid"  : "ProtoGENI Identifier (an x509 certificate)",
  "url"  : "URL of the XML-RPC server",
}

Availability: supported in revisions 0 to 1.

Remove

Remove a principle object from the clearing house database.

int Remove(credential, uuid, type);

where credential is the credential returned by the GetCredential() call above, uuid is the uuid of the object to be removed, and type is one of Slice|User.

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 revisions 0 to 1.

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, uuid);

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

The return value is success or failure.

Availability: supported in revisions 0 to 1.

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 the manager. The URL and HRN can be extracted from the GID, but as a convenience the array includes these as well.

({
  "gid"  : "ProtoGENI Identifier (an x509 certificate)",
  "hrn"  : "Human Readable Name (HRN)",
  "url"  : "URL of the XML-RPC server",
 }
 ...
)

Availability: supported in revisions 0 to 1.

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 1.

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", "hrn" and "uuid" fields corresponding to each available object.

Availability: supported in revisions 0 to 1.

GetVersion

int GetVersion();

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

Availability: supported in revision 1 only.