Changes between Version 32 and Version 33 of UniformClearinghouseAPIV2


Ignore:
Timestamp:
12/10/13 12:11:12 (10 years ago)
Author:
mbrinn@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • UniformClearinghouseAPIV2

    v32 v33  
    2727 * '' Slice Authority '' [SA]: Manages slice objects and generates credentials for members with respect to slices.
    2828
    29 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 Registry is a software service 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 Registries is 1:1.
     29A '' Federation '' is a collection of Authorities and Aggregates that establish mutual trust and common policies to facilitate the sharing of resources among members. A Federation Registry is a software service 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 Federation Registries is 1:1.
    3030
    3131The 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.
    3232
    33 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 Registry may choose to advertise or not advertise any particular aggregate, regardless of whether that aggregate trusts the Authorities advertised by that Registry. Similarly, a given Slice Authority or Member Authority may be advertised by a single Registries or by multiple Registries. Registry API calls are unprotected. There is no notion of trust between Registries or between Registries and Authorities or Aggregates.
    34 
    35 This document describes the APIs of the Registry as well as the MA and SA. It is expected that a well-behaved GENI-compatible tool will allow for interacting with any Registry and Authority that implement the standard API’s described in this document.
     33Authorities 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 Federation Registry may choose to advertise or not advertise any particular aggregate, regardless of whether that aggregate trusts the Authorities advertised by that Federation Registry. Similarly, a given Slice Authority or Member Authority may be advertised by a single Federation Registries or by multiple Federation Registries. Federation Registry API calls are unprotected. There is no notion of trust between Federation Registries or between Federation Registries and Authorities or Aggregates.
     34
     35This document describes the APIs of the Federation Registry as well as the MA and SA. It is expected that a well-behaved GENI-compatible tool will allow for interacting with any Federation Registry and Authority that implement the standard API’s described in this document.
    3636
    3737
    … …  
    5050 * 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 requirement for a validated client-side certificate . Such calls will noted in the API documentation below.
    5151 * Each call takes an ‘options’ argument, a dictionary allowing for passing specific non-standard/optional arguments
    52  * Each protected method takes a ‘credentials’ argument, a list of type/credential tuples that help the Registry or Authority invoke whatever AuthZ logic it may choose. As noted above, the Registry or Authority may choose to use or disregard these credentials. Unprotected methods do not take a ‘credentials’ argument.
    53  * Each Registry 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.
    54  * A Registry or Authority is free to implement additional methods beyond those specified in this document.
     52 * Each protected method takes a ‘credentials’ argument, a list of type/credential tuples that help the Federation Registry or Authority invoke whatever AuthZ logic it may choose. As noted above, the Federation Registry or Authority may choose to use or disregard these credentials. Unprotected methods do not take a ‘credentials’ argument.
     53 * Each Federation Registry 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.
     54 * A Federation Registry or Authority is free to implement additional methods beyond those specified in this document.
    5555 * The URN is the fundamental identifier in all Federation 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. The format of URN's is documented at http://groups.geni.net/geni/wiki/GeniApiIdentifiers.
    5656
    … …  
    7979Different Federation Authorities will provide different sets of methods bundled into services. Further, they will manage different kinds of objects and support different details for these objects.
    8080
    81 Each Registry or Authority 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):
     81Each Federation Registry or Authority 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):
    8282 * VERSION: A string with the version number of the Federation API (e.g. “2”, the version for this document). Note: this is the version of the API not the version of the implementation. This field is mandatory for all services.
    83  * URN : The URN of the service being contacted. This field is mandatory for SA and MA services, optional for Registry service.
     83 * URN : The URN of the service being contacted. This field is mandatory for SA and MA services, optional for Federation Registry service.
    8484 * IMPLEMENTATION: A dictionary of information of the implantation of the service: {"code_version" : code_version, "code_url" : code_url, "code_release_date" : code_release_date, "site_update_date" : site_update_date"}. Of these, code_version is of type STRING, code_url is of type URL,  code_release_date and site_update_date are of format DATETIME. The format of the code_version string is implementation specific. This field is optional for services.
    8585 * SERVICES: The list of names of services the given URL supports. This field is optional (with default being the default service for that authority, i.e. SERVICE for Federation Registry, SLICE for Slice Authority, MEMBER for MemberAuthority). 
    8686 * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [geni_sfa, geni_abac]) and list of supported credential versions on protected API methods.  Format is analogous to that in the AM API: a list of {"type": cred_type, "version" : cred_version} dictionaries of all supported credential types and versions. ''[Required for Authorities only]''
    87  * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership).  ''[Required for SA only]''
     87 * ROLES : A list of recognized roles for slice/project membership (required only for those Slice Authorities supporting membership). The same set of roles refers to both slice and project membership at a given SA.
    8888 * SERVICE_TYPES. A list of service types provided by the Federation Registry ''[Required for Federation Registry only]''
    8989 * API_VERSIONS A dictionary of different peer implementation of different version of the same service. This field is optional for all services.
    … …  
    9898The FIELDS element of the get_version should contain all supplementary (non-mandatory) field objects supported by a given service. Additionally, it may contain mandatory field objects for which the default semantics (for "CREATE", "MATCH", "UPDATE", "PROTECT") should be overridden. Specifically, any values specified override the default values and any values unspecified are defined to be the defaults for that object/field in this document. The FIELDS element is thus optional for all services.
    9999
     100The set of ROLES may vary across Slice Authorities based on local policy. However, the following roles should be defined at any Slice Authority:
     101
     102|| '''Role''' || '''Contex'''' || '''Description''' ||
     103|| LEAD || PROJECT || May change project membership and create slices within a given project ||
     104|| || SLICE || May change slice membership  and perform operations on a given slice||
     105|| MEMBER || PROJECT || May create slices within given project ||
     106|| || SLICE || May perform operations on given slice ||
     107
    100108Supplementary field names should be placed in a distinct namespace by a prefix unique to that federation, and starting with an underscore (e.g. _GENI_,  _OFELIA_ , _FED4FIRE_ or _PROTOGENI_ etc.).
    101109
    … …  
    108116}}}
    109117
    110 The return from the get_version call will be used to construct and validate options to Registry and Authority API calls, as described in subsequent sections.
     118The return from the get_version call will be used to construct and validate options to Federation Registry and Authority API calls, as described in subsequent sections.
    111119
    112120The get_version method at any service has the following signature:
    … …  
    214222All method calls return a tuple [code, value, output]. What is described as ‘Return’ in the API’s described below is the ‘value’ of this tuple in case of a successful execution. ‘Code’ is the error code returned and ‘output’ is the returned text (e.g. descriptive error message).
    215223
    216 Each Registry and Authority is free to define and return its own specific error codes. However we suggest the following essential set of error codes to report on generic conditions:
     224Each Federation Registry and Authority is free to define and return its own specific error codes. However we suggest the following essential set of error codes to report on generic conditions:
    217225
    218226|| ''' CODE_NAME ''' || ''' CODE_VALUE ''' || ''' DESCRIPTION ''' ||
    … …  
    228236== Standard API Method ==
    229237
    230 Each Registry and Authority manages the state of or access to objects. There are some standard methods that apply to standard operations on objects of specific types. All services support the following API's for the object types that are required or provided in get_version.
     238Each Federation Registry and Authority manages the state of or access to objects. There are some standard methods that apply to standard operations on objects of specific types. All services support the following API's for the object types that are required or provided in get_version.
    231239
    232240{{{
    … …  
    453461Best practices dictate that individuals should speak as themselves: that is, the entity on the other side of an SSL connection is the one referred to by the certificate on the connection. Obviously, people typically use tools or software interfaces to create these connections. When a tool is acting directly on a user’s desktop using the user’s key and cert with the user’s explicit permission, it may be acceptable to consider the tool as speaking as the user. But for many tools, the tool is acting on behalf of the user in invoking Federation or AM API calls. In this case, it is important for the tool to not speak as the user but to speak for the user, and to have the service to whom the tool is speaking handle the authorization and accountability of this request accordingly.
    454462
    455 Accordingly, a Registry and associated Authorities should support speaks-for API transactions. These API transactions use the same signatures as the calls described in this document, with these enhancements:
     463Accordingly, a Federation Registry and associated Authorities should support speaks-for API transactions. These API transactions use the same signatures as the calls described in this document, with these enhancements:
    456464
    457465- A 'speaking-for' option containing the URN of the user being spoken for
    … …  
    463471Aggregates are also encouraged to support speaks-for authentication and authorization, but this is an aggregate-internal policy and implementation decision, and outside the scope of this document.
    464472
    465 == Registry API ==
    466 
    467 The Registry provides a list of Slice Authorities, Member Authorities and Aggregates associated with a given Federation. The URL for accessing these methods (i.e. the URL of the Registry) is to be provided out-of-band (i.e. there is no global service for gaining access to Registry addressees).
    468 
    469 All Registry calls are unprotected; they have no requirement for passing a client-side cert or validating any client-cert cert that is passed.
    470 
    471 The Registry implements the SERVICE service and supports the SERVICE object.
    472 
    473 Services have a particular type that indicates the kind of service it represents. The full list of supported services should be provided by a TYPES key in the Registry get_version call, for example:
     473== Federation Registry API ==
     474
     475The Federation Registry provides a list of Slice Authorities, Member Authorities and Aggregates associated with a given Federation. The URL for accessing these methods (i.e. the URL of the Federation Registry) is to be provided out-of-band (i.e. there is no global service for gaining access to Federation Registry addressees).
     476
     477All Federation Registry calls are unprotected; they have no requirement for passing a client-side cert or validating any client-cert cert that is passed.
     478
     479The Federation Registry implements the SERVICE service and supports the SERVICE object.
     480
     481Services have a particular type that indicates the kind of service it represents. The full list of supported services should be provided by a TYPES key in the Federation Registry get_version call, for example:
    474482
    475483{{{
    … …  
    492500|| LOGGING_SERVICE || A service to support federation-level event logging ||
    493501
    494 The following table describes the standard fields for services (aggregates and authorities) provided by Registry API calls. (The 'Required' column indicates whether the field must be present for a valid service, 'match' indicates whether the field can be used in a lookup match criterion):
     502The following table describes the standard fields for services (aggregates and authorities) provided by Federation Registry API calls. (The 'Required' column indicates whether the field must be present for a valid service, 'match' indicates whether the field can be used in a lookup match criterion):
    495503
    496504
    … …  
    498506|| SERVICE_URN || URN || URN of given service || Yes || Yes ||
    499507|| SERVICE_URL ||URL || URL by which to contact the service || Yes || Yes ||
    500 || SERVICE_TYPE || STRING || Name of service type (from Registry get_version.TYPES) || Yes || Yes ||
     508|| SERVICE_TYPE || STRING || Name of service type (from Federation Registry get_version.TYPES) || Yes || Yes ||
    501509|| SERVICE_CERT || Certificate || Public certificate of service || No || No ||
    502510|| SERVICE_NAME || String || Short name of service || Yes || No ||
    … …  
    517525}}}
    518526
    519 The Registry API supports these standard API methods for type="SERVICE":
     527The Federation Registry API supports these standard API methods for type="SERVICE":
    520528
    521529|| ''' Method ''' || ''' Description ''' ||
    522530|| lookup || lookup services matching given match criteria. ||
    523531
    524 Additionally, the Registry API supports the following methods:
     532Additionally, the Federation Registry API supports the following methods:
    525533
    526534{{{
    … …  
    548556# There should be at most one (potentially none) per URN.
    549557#
    550 # This requires extracting the authority from the URN and then looking up the authority in the Registry's set of services.
     558# This requires extracting the authority from the URN and then looking up the authority in the Federation Registry's set of services.
    551559#
    552560# Arguments:
    … …  
    744752== Project Service Methods ==
    745753
    746 Projects are groupings of slices and members for a particular administrative purpose. Some SA;s will chose to create and manage projects and apply policies about the invocation of SA methods (e.g. the creation of slice credentials based on roles or memberships in projects).
     754Projects are groupings of slices and members for a particular administrative purpose. Some SA;s will chose to create and manage projects and apply policies about the invocation of SA methods (e.g. the creation of slice credentials based on roles or memberships in projects). A slice can belong to no more than one project; a project may have many slice members.
    747755
    748756The following table contains required fields for project objects and whether they are allowed in lookup ‘match’ criteria, required at creation or allowed at update:
    … …  
    904912
    905913|| ''' Authority ''' || ''' V1 method ''' || ''' V2 alternative '' ||
    906 || Registry || || ||
     914|| Federation Registry || || ||
    907915||   || lookup_aggregates || lookup(type="AGGREGATE_MANAGER") ||
    908916||  || lookup_slice_authorities || lookup(type="SLICE_AUTHORITY") ||