Changes between Version 41 and Version 42 of UniformClearinghouseAPI


Ignore:
Timestamp:
08/29/13 06:23:56 (11 years ago)
Author:
mbrinn@bbn.com
Comment:

Change Clearinghouse to Registry, API is called Uniform Federation API

Legend:

Unmodified
Added
Removed
Modified

  • UniformClearinghouseAPI

    v41 v42  
    11[[PageOutline(1-2, Table of Contents)]]
    2 == GENI Clearinghouse API’s ==
     2== GENI Federation API’s ==
    33Marshall Brinn, GPO
    44
    … …  
    1010
    1111
    12 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.
     12This document proposes a set of standard API’s that any GENI-compatible Federation should or may provide. The document describes what is required and what is optional in the calls and responses to these APIs.
    1313
    1414The GENI Software Architecture rests on the interaction between different entities:
    … …  
    2525 * '' Slice Authority '' [SA]: Manages slice objects and generates credentials for members with respect to slices.
    2626
    27 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.
     27A '' 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.
    2828
    2929The 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.
    3030
    31 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.
    32 
    33 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.
     31Authorities 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.
     32
     33This 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.
    3434
    3535
    … …  
    5050        ''NB: This is an ''' unprotected call ''', no client cert required.''
    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 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.
    53  * 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.
    54  * A CH or Authority is free to implement additional methods beyond those specified in this document.
    55  * 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.
     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.
     55 * 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.
    5656
    5757These API’s are provided in pseudo-code (i.e. language independent) format, with inputs and outputs (optional and required) described by comments, e.g.
    … …  
    6060/*
    6161
    62 ''Perform method ‘ch_func’''
     62''Perform method ‘fed_func’''
    6363
    6464'''Arguments:'''
    … …  
    7171[[BR]]E.g. a list of dictionaries with these fields mandatory (…) and these fields optional (…)
    7272[[BR]]*/
    73 [[BR]]''function '''ch_func''' (arg1, arg2, credentials, options)''
     73[[BR]]''function '''fed_func''' (arg1, arg2, credentials, options)''
    7474
    7575
    7676== API 'get_version' methods ==
    7777
    78 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.
    79 
    80 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):
     78Different 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.
     79
     80Each 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):
    8181 * VERSION: The version number of the API (e.g. “10.0.7”)
    8282 * SERVICES: The set of services the given URL supports (only for Slice Authority)
    8383 * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [ABAC, SFA]) and list of supported credential versions on protected API methods.
    8484 * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership)
    85  * OBJECTS : List of additional supported objects (e.g. PROJECT in SA). Not needed for only standard objects (e.g. SLICE in SA, MEMBER in MA, SERVICE in CH).
     85 * OBJECTS : List of additional supported objects (e.g. PROJECT in SA). Not needed for only standard objects (e.g. SLICE in SA, MEMBER in MA, SERVICE in Registry).
    8686 * FIELDS: A dictionary of '''''supplementary''''' object field names (i.e. in additional to the required fields) and associated attributes including:
    87      * “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)
     87     * “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 Registry)
    8888     * “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.]
    8989     * “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.
    … …  
    9292     * “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.
    9393
    94 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.
     94The 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.
    9595
    9696The following page provides some example returns from different get_version calls.
    … …  
    152152}
    153153
    154 The following is an example of a return from a get_version from a CH, provided in JSON-like syntax:
     154The following is an example of a return from a get_version from a Registry, provided in JSON-like syntax:
    155155
    156156{
    … …  
    169169All 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).
    170170
    171 Each CH 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:
     171Each 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:
    172172
    173173|| ''' CODE_NAME ''' || ''' CODE_VALUE ''' || ''' DESCRIPTION ''' ||
    174174|| NONE || 0 || No error encountered – the return value is a successful result. An empty list form a query should be interpreted as ‘nothing found matching criteria’. ||
    175 || AUTHENTICATION_ERROR || 1 || The invoking tool or member did not provide appropriate credentials indicating that they are known to the CH or that they possessed the private key of the entity they claimed to be ||
     175|| AUTHENTICATION_ERROR || 1 || The invoking tool or member did not provide appropriate credentials indicating that they are known to the Federation or that they possessed the private key of the entity they claimed to be ||
    176176|| AUTHORIZATION_ERROR || 2 || The invoking tool or member does not have the authority to invoke the given call with the given arguments ||
    177177|| ARGUMENT_ERROR || 3 || The arguments provided to the call were mal-formed or mutually inconsistent. ||
    … …  
    182182== API Method Conventions ==
    183183
    184 Each CH and Authority manages the state of or access to objects. Some conventions apply to similar methods across CH or Authority services.
     184Each Registry and Authority manages the state of or access to objects. Some conventions apply to similar methods across Registry or Authority services.
    185185
    186186''' Create_*Method ''' : Creates a new instance of the given object with a ‘fields’ option specifying particular field values that are to be associated with the object. These may only include those fields specified as ‘ALLOWED or ‘REQUIRED’ in the ‘Creation’ column of the object descriptions below or in the “CREATE’ key in the supplemental fields in the get_version specification for that object. If successful, the call returns a dictionary of the fields associated with the newly created object.
    … …  
    311311== API Authentication ==
    312312
    313 This document suggests that the Authentication required for the CH is implicit in the SSL protocol: the invoker of the call must have its cert and private key to have a valid SSL connection. Moreover, the cert must be signed by a member of the trust chain recognized by the CH.
     313This document suggests that the Authentication required for the Federation APIs is implicit in the SSL protocol: the invoker of the call must have its cert and private key to have a valid SSL connection. Moreover, the cert must be signed by a member of the trust chain recognized by the Federation.
    314314
    315315== Support for Speaks-for API Invocations ==
    316316
    317 Best 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 CH 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.
    318 
    319 Accordingly, a Clearinghouse 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:
     317Best 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.
     318
     319Accordingly, 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:
    320320
    321321- A 'speaking-for' option containing the URN of the user being spoken for
    … …  
    323323- A speaks-for credential in the list of credentials: a statement signed by the user indicating that the tool has the right to speak for the user, possibly limited to a particular scope (e.g. slice, project, API call, time window).
    324324
    325 The CH is then required to determine if the call is being made in a speaks-for context or not (that is, the ‘speaking-for’ option provided). If so, the CH call must determine if the tool is allowed to speak for the user by checking for the presence of a valid speaks-for credential and the spoken-for user’s cert. If so, the CH should validate if the user is authorized to take the proposed API action. If so, the action is taken and accounted to the user, with identity of the speaking-for tool logged. If the call is ‘speaks-for’ but any of these additional criteria are not met, the call should fail with an authorization error. If the call is not a ‘speaks-for’, then the normal authorization is performed based on the identity (certificate) provided with the SSL connection.
     325The service call is then required to determine if the call is being made in a speaks-for context or not (that is, the ‘speaking-for’ option provided). If so, the call must determine if the tool is allowed to speak for the user by checking for the presence of a valid speaks-for credential and the spoken-for user’s cert. If so, the call should validate if the user is authorized to take the proposed API action. If so, the action is taken and accounted to the user, with identity of the speaking-for tool logged. If the call is ‘speaks-for’ but any of these additional criteria are not met, the call should fail with an authorization error. If the call is not a ‘speaks-for’, then the normal authorization is performed based on the identity (certificate) provided with the SSL connection.
    326326
    327327Aggregates 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.
    328328
    329 == Clearinghouse API ==
    330 
    331 The Clearinghouse 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 Clearinghouse) is to be provided out-of-band (i.e. there is no global service for gaining access to CH addressees).
    332 
    333 The following table describes the default fields for services (aggregates and authorities) provided by CH API calls:
     329== Registry API ==
     330
     331The 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).
     332
     333The following table describes the default fields for services (aggregates and authorities) provided by Registry API calls:
    334334
    335335
    … …  
    344344/*
    345345
    346 Provide a structure detailing the version information as well as details of accepted options s for CH API calls.
     346Provide a structure detailing the version information as well as details of accepted options for Registry API calls.
    347347
    348348NB: This is an '''unprotected''' call, no client cert required.
    … …  
    421421There should be at most one (potentially none) per URN.
    422422
    423 This requires extracting the authority from the URN and then looking up the authority in the CH set of services.
     423This requires extracting the authority from the URN and then looking up the authority in the Registry's set of services.
    424424
    425425NB: This is an unprotected call, no client cert required.
    … …  
    439439/*
    440440
    441 Return list of trust roots (certificates) associated with this CH.
     441Return list of trust roots (certificates) associated with this Federation.
    442442
    443443Often this is a concatenatation of the trust roots of the included authorities.
    … …  
    451451'''Return:'''
    452452
    453 List of certificates representing trust roots of this CH.
     453List of certificates representing trust roots of this Federation.
    454454
    455455*/
    … …  
    473473The Slice Authority manages the creation of slices, which are containers for allocating resources. It provides credentials (called slice credentials) which aggregates may use to make authorization decisions about allocating resources to a particular user to a particular slice. These slice credentials are one of the fields that may be provided from the create_slice call or requested in the lookup_slices call.
    474474
    475 Note that renewal of slice expiration is handled in the update_slice call (with “SLICE_EXPIRATION” specified as the options key. The semantics of slice expiration is that slice expiration may only be extended, never reduced. Further restrictions (relative to project expiration or relative to slice creation, e.g.) are CH-specific.
     475Note that renewal of slice expiration is handled in the update_slice call (with “SLICE_EXPIRATION” specified as the options key. The semantics of slice expiration is that slice expiration may only be extended, never reduced. Further restrictions (relative to project expiration or relative to slice creation, e.g.) are SA-specific.
    476476
    477477The following table contains required fields for slice objects and whether they are allowed in lookup ‘match’ criteria, required at creation or allowed at update:
    … …  
    573573==Slice Member Service Methods ==
    574574
    575 Slices may have a set of members associated with them in particular roles. Certain CH’s may have policies that require certain types of membership requirements (exactly one lead, never empty, no more than a certain number of members, etc.). To that end, we provide a single omnibus method for updating slice membership in a single transaction, allowing any authorization or assurance logic to be supported at a single point in CH implementations.
     575Slices may have a set of members associated with them in particular roles. Certain SA may have policies that require certain types of membership requirements (exactly one lead, never empty, no more than a certain number of members, etc.). To that end, we provide a single omnibus method for updating slice membership in a single transaction, allowing any authorization or assurance logic to be supported at a single point in SA implementations.
    576576
    577577The set of recognized role types (e.g. LEAD, ADMIN, MEMBER, OPERATOR, AUDITOR) are to be listed in the get_version for a given Slice Authority.
    … …  
    680680Provide a list of URLs of all aggregates that have been registered as having resources allocated with a given slice.
    681681
    682 NB: This list is not definitive in that the aggregate may not have called the register_aggregate call, and that the slivers may no longer be at the aggregate. But it is provided as a convenience for tools to know where to go for sliver information (rather than querying every aggregate in the CH).
     682NB: This list is not definitive in that the aggregate may not have called the register_aggregate call, and that the slivers may no longer be at the aggregate. But it is provided as a convenience for tools to know where to go for sliver information (rather than querying every aggregate in the Registry).
    683683
    684684'''Arguments:'''
    … …  
    696696== Project Service Methods ==
    697697
    698 Projects are groupings of slices and members for a particular administrative purpose. Some CH’s will chose to create and manage projects and apply policies about the invocation of CH methods (e.g. the creation of slice credentials0 based on roles or memberships in projects.
     698Projects 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).
    699699
    700700The following table contains required fields for project objects and whether they are allowed in lookup ‘match’ criteria, required at creation or allowed at update:
    … …  
    819819== Member Authority API ==
    820820
    821 As noted above, this document does not specify required policies for Clearinghouses. A given CH is free to implement its own policies. That said, the management of member private information is a subject for particular attention and care.
     821As noted above, this document does not specify required policies for Federations. A given MA is free to implement its own policies. That said, the management of member private information is a subject for particular attention and care.
    822822
    823823The protected APIs described here are standard SSL calls and can be invoked by anyone with their own SSL cert and private key. Reasonable security policy, however, should allow this call to succeed only if the following criteria are met:
    824824
    825  * The user/tool cert is signed by someone in the CH’s trust chain
    826  * If the cert is held by a tool, then the call must contain a user cert and a ‘speaks-for’ credential and the tool is trusted by the CH to perform speaks-for.
     825 * The user/tool cert is signed by someone in the Federation's trust chain
     826 * If the cert is held by a tool, then the call must contain a user cert and a ‘speaks-for’ credential and the tool is trusted by the Federation to perform speaks-for.
    827827 * The requestor is asking for their own identifying info or has privileges with respect to the people about whom they are asking for that identifying info.
    828828 * Access to private info (SSL or SSH keys) should be restricted only to the user’s own keys for ordinary users.
    … …  
    949949function '''get_credentials'''(member_urn, credentials, options)
    950950
    951 == Appendix: CH Object Models ==
    952 
    953 As described, each CH service method takes a set of options that provide further details on the request. Many of these options reflect the fields of the underlying object models. For example, the Slice Authority manages slice objects and allows for options for querying for and by slice object fields.
    954 
    955 Different Clearinghouses will implement different subsets of the possible set of CH services. Those that do implement a given service should implement the API’s described above. The fields of the objects maintained through these API’s are flexible: some fields are required but different Clearinghouses may have their own additional data, to be returned by the get_version method.
    956 
    957 The following diagram reflects the different objects maintained within the full range of CH services, their interactions and mandatory fields.
     951== Appendix: Federation Object Models ==
     952
     953As described, each Federation service method takes a set of options that provide further details on the request. Many of these options reflect the fields of the underlying object models. For example, the Slice Authority manages slice objects and allows for options for querying for and by slice object fields.
     954
     955Different Federation Authorities will implement different subsets of the possible set of Federation services. Those that do implement a given service should implement the API’s described above. The fields of the objects maintained through these API’s are flexible: some fields are required but different Authorities may have their own additional data, to be returned by the get_version method.
     956
     957The following diagram reflects the different objects maintained within the full range of Authority services, their interactions and mandatory fields.
    958958
    959959[[Image(CHObjectModel.pdf, 50%,nolink)]]