wiki:UniformClearinghouseAPI

Version 3 (modified by jmccolga@bbn.com, 6 years ago) (diff)

--

GENI Clearinghouse API’s

Marshall Brinn, GPO

DRAFT: August 6, 2013

Introduction

This document proposes a set of standard API’s that any GENI Clearinghouse (CH) should or may provide. The document describes what is required and what is optional in the calls and responses to these APIs.

The GENI Software Architecture rests on the interaction between different entities:

Aggregates : Collections of resources managed and presented in accordance with the AM API

Members : Experimenters or other human consumers of aggregate resources

Authorities : Services that manage assertions about members and their permissions with respect to aggregate resources.

There are two fundamental authority types in GENI:

  • Member Authority [MA]: Manages and asserts attributes about particular members
  • Slice Authority [SA]: Manages slice objects and generates credentials for members with respect to slices.

A Federation is a collection of Authorities and Aggregates that establish mutual trust and common policies to facilitate the sharing of resources among members. A Clearinghouse (CH) is a set of software services representing a given Federation, providing lists of Slice Authorities, Member Authorities and aggregates associated with that federation, and providing a set of PKI certificates that any aggregate belonging to a given federation accepts as trust roots. The relationship of Federations to Clearinghouses is 1:1.

The Authorities of any given Federation are free to implement their own Authorization (AuthZ) scheme. The API’s allow for passing credentials to the calls, but an Authority may choose to allow or disallow calls using logic and policies that are internal to that Federation. There is no universal (cross-Federation) requirement for any particular policy regarding Authority AuthZ.

Authorities are fundamentally independent of one another. The objects defined at one Authority are not necessarily entitled to any services provided by another Authority. Each aggregate may choose to trust or not trust any particular Authority. Likewise, any Authority may chose to trust or not trust any other Authority. A CH may choose to advertise or not advertise any particular aggregate, regardless of whether that aggregate trusts the Authorities advertised by that CH. Similarly, a given Slice Authority or Member Authority may be advertised by a single CH or by multiple CH’s. CH API calls are unprotected: there is no notion of trust between CH’s or between CH’s and Authorities or Aggregates.

This document describes the APIs of the GENI CH as well as the MA and SA. It is expected that a well-behaved GENI tool will allow for interacting with any CH and Authority that implement the standard API’s described in this document.

API General Properties

The APIs described here share some common properties, which should be assumed for the rest of this document:

  • The wire-protocol is XML/RPC. It is thus language independent on both client and server side of the API calls.
  • Most calls are protected, running over SSL and thus requiring the caller to use its certificate and private key. Certain calls are unprotected and can be accessed with no certificate and private key.
  • Unprotected calls will be identified in API documentation with the annotation:

NB: This is an unprotected call , no client cert required.

  • Each call takes an ‘options’ argument, a dictionary allowing for passing specific non-standard/optional arguments
  • Each protected method takes a ‘credentials’ argument, a list of type/credential tuples that help the CH or Authority invoke whatever AuthZ logic it may choose. As noted above, the CH or Authority may choose to use or disregard these credentials. Unprotected methods do not take a ‘credentials’ argument.
  • Each CH or Authority provides a get_version method, which describes the version number of the API provided, credential types supported, supplementary object fields and other data for interpreting API call returns.
  • A CH or Authority is free to implement additional methods beyond those specified in this document.
  • The URN is the fundamental identifier in all GENI CH API’s. URN’s are globally unique at any given time, though not necessarily unique over time. Disambiguation for entities with the same URN over time may be provided by an optional UUID argument for certain API methods.

These API’s are provided in pseudo-code (i.e. language independent) format, with inputs and outputs (optional and required) described by comments, e.g.

/*

Perform method ‘ch_func’

Arguments

argl : ...

credentials : list of {type : credential} tuples representing credentials provided by caller to support AuthZ on method call. [NB: This argument will be omitted in descriptions below. ] options : … [ Recognized options: ….]

Return : E.g. a list of dictionaries with these fields mandatory (…) and these fields optional (…)

*/

function ch_func (arg1, arg2, credentials, options)

API 'get_version' methods

Different Clearinghouses will provide different sets of methods bundled into services. Further, they will manage different kinds of objects and support different details for these objects.

The CH API provides a ‘get_version’ method, which provides information to the caller (or a tool composing calls for a tool user) about versions and options supported by that API. The call takes no argument and is unguarded (anyone can call it). The return from the get_version call will be a dictionary including the following entries (by key):

  • VERSION: The version number of the API (e.g. “10.0.7”)
  • SERVICES: The set of services the given URL supports (only for Slice Authority)
  • CREDENTIAL_TYPES: A list of recognized credential types (e.g. [ABAC, SFA]) on protected API methods.
  • ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership)
  • FIELDS: A dictionary of supplementary object field names (i.e. in additional to the required fields) and associated attributes including:
    • “OBJECT” provides the object to which the field belongs (if not the default authority object, i.e. SLICE for Slice Authority, MEMBER for Member Authority, Service for Clearinghouse)
    • “TYPE” may be one of “URN”, “UID”, “STRING”, “DATETIME”, “EMAIL”, “KEY”,“BOOLEAN”, “CREDENTIAL”, “CERTIFICATE”. [NB. This set of types subject to change. See Appendix for more information on these data types.]
    • “CREATE” attributes may be specified as “REQUIRED”, “ALLOWED” or “NOT ALLOWED” (default = “NOT ALLOWED”). These indicate whether the given supplementary field is required, allowed or prohibited in create calls.
    • “UPDATE” attributes may be specified as TRUE or FALSE (default = FALSE). These indicate whether the given field may be specified in an update call.
    • “PROTECT” attributes may be labeled as “PUBLIC”, “PRIVATE” or “IDENTIFYING”. These are for the Member Authority Only to differentiate between public, identifying and private data fields on members.

The return from the get_version call will be used to construct and validate options to CH and Authority API calls, as described in subsequent sections.

The following page provides some example returns from different get_version calls.

Example get_version returns:

The following is an example of a return from a get_version for an SA. The responses are all dictionaries via XMLRPC into the native implementation. They are shown here in JSON-like syntax:

{

“VERSION”: “10.0.7”, “SERVICES”: [“SLICE”, “PROJECT”, “SLICE_MEMBER”, “PROJECT_MEMBER”] “CREDENTIAL_TYPES”: [“SFA”, “ABAC”], “ROLES” : [“LEAD”, “ADMIN”, “MEMBER”, “AUDITOR”, “OPERATOR” ], “FIELDS”:

“PROJECT_URN”: {“TYPE”: “URN”, “CREATE”: “REQUIRED”, “UPDATE”: FALSE}, “SLICE_EMAIL”: {“TYPE”: “EMAIL”, “CREATE”: “REQUIRED”, “UPDATE”: TRUE} “PROJECT_EMAIL”: {“TYPE”: “EMAIL”, “CREATE”: “REQUIRED”, “UPDATE”: TRUE, “OBJECT”: “PROJECT”}

}

}

}