Changes between Version 15 and Version 16 of UniformClearinghouseAPIV2


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

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPIV2

    v15 v16  
    9999The 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.
    100100
     101The get_version method at any service has the following signature:
     102{{{
     103#!python
     104# Return information about version and options (filter, query, credential types) accepted by this service
     105#
     106# Arguments: None
     107#
     108# Return:
     109#     get_version structure information as described above
     110def get_version()
     111}}}
     112
     113
    101114The following page provides some example returns from different get_version calls.
    102115
     
    421434    {
    422435       …
    423        "TYPES" : ["SLICE_AUTHORITY", "MEMBER_AUTHORITY", "AGGREGATE_MANAGER", "LOGGING_SERVICE"]
     436       "TYPES" : ["SLICE_AUTHORITY", "MEMBER_AUTHORITY", "AGGREGATE_MANAGER", ...]
    424437       …
    425438    }
     
    434447|| STITCHING_COMPUTATION_SERVICE || A toplogy service for supporting cross-aggregate stitching ||
    435448|| CREDENTIAL_STORE || A service holding credentials for the federation, typically for supporting federation authentication services ||
    436 || LOGGING_SERVICE | A service to support federation-level event logging ||
     449|| LOGGING_SERVICE || A service to support federation-level event logging ||
    437450
    438451The following table describes the default fields for services (aggregates and authorities) provided by Registry API calls ('Required' indicates whether the field must be present for a valid service, 'match' indicates whether the field can be used in a lookup match criterion):
     
    883896|| MEMBER_EMAIL || STRING || Email of user || Yes || Identifying ||
    884897
    885 {{{
    886 #!python
    887 # Return information about version and options (filter, query, credential types) accepted by this member authority
    888 #
    889 # Arguments: None
    890 #
    891 # Return:
    892 #     get_version structure information as described above
    893 def get_version()
    894 }}}
    895 
    896 {{{
    897 #!python
    898 # Lookup information about members matching given criteria
    899 # Provide public information for all members
    900 # Provide identifying (e.g. email or name) or private (e.g. SSL/SSH private key) information for members for whom callers is authorized
    901 # Where a field requested is unauthorized, the key will not be provided in the returned dictionary for that member
    902 # When the field requested has a key but a blank/null value, the access is authorized but the value for that field is, in fact, blank
    903 #
    904 # Arguments:
    905 #   options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
    906 #
    907 # Return:
    908 #   Dictionary indexed by member URN of dictionaries of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
    909 def lookup(credentials, options)
    910 }}}
    911 
    912 
    913 {{{
    914 #!python
    915 # Update information about given member public, private or identifying information
    916 #
    917 # Arguments:
    918 #    member_urn: URN of member for whom to set information
    919 #    options: Containing ‘update’ key with dictionary of name/value pairs to update info for given member
    920 #
    921 # Return: None
    922 def update(type, member_urn, credentials, options)
    923 }}}
     898The MEMBER Service supports these standard API methods for type="MEMBER", with elaboration in the following table:
     899
     900|| ''' Method ''' || ''' Description ''' ||
     901|| update ||  update info associated with given member by URN ||
     902|| lookup || lookup info associated with members matching match criteria. ||
     903
     904Note: the ''lookup' call provides public information for all members matching the 'match' criteria. It will also provide identifying (e.g. email or name) or private (e.g. SSL private key) information for members for whom the caller is authorized.
     905When a field requested is unauthorized, the key will not be provide in the returned dictionary for that member.
     906When the field requested has a key but a blank/null value, the access is authorized but the value for that field is, in fact, blank.
     907A blank (null, not empty list) fields option indicates that the caller wants to see all fields to which the caller  is authorized. If a list of fields is specified in the fields option, only those authorized fields from among the specified set is provided for each matched member.
     908
     909The following are additional methods provided by the MEMBER service:
    924910
    925911{{{
     
    949935|| KEY_DESCRIPTION || STRING || Human readable description of key pair || Yes || Allowed || Yes ||
    950936
     937
     938The Key Service supports these standard API methods for type="KEY", with elaboration in the following table:
     939
     940|| ''' Method ''' || ''' Description ''' ||
     941|| create || Creates a new record for a key associated with a member. The 'KEY_ID' returned from this call is the unique identifier for this key for this member and can be used as the 'urn' variable in the other key management API calls below. ||
     942|| update || urn is the key_id ||
     943|| delete || urn is the key_id ||
     944|| lookup || lookup keys matching given match criteria subject to authorization restrictions. ||
     945
    951946Note that access to key information is subject to authorization policy. The public keys are likely to be readily available but access to the private keys will be tightly restricted (often only to the user or authorized proxy). Requests to lookup information for which the requestor is not authorized should fail on, at least, a per row basis. That is, if one asks for KEY_PUBLIC and KEY_PRIVATE for a list of member_urn's, the key pair should be returned only for those members to whom access to BOTH halves of the key are allowed. Note also that storing the private key is optional: an empty private key returned from a lookup method is an indication that no such key is stored, not that the access to the private key is not authorized.
    952947
    953 {{{
    954 #!python
    955 # Create a record for a key pair for given member
    956 #
    957 # Arguments:
    958 #    options: 'fields' containing the fields for the key pair being stored
    959 #
    960 # Return:
    961 #    Dictionary of name/value pairs for created key record including the KEY_ID
    962 #
    963 # Should return DUPLICATE_ERROR if a key with the same KEY_ID is already stored for given user
    964 def create_key(credentials, options)
    965 }}}
    966 
    967 {{{
    968 #!python
    969 # Delete a key pair for given member
    970 #
    971 # Arguments:
    972 #    member_urn: urn of member for which to delete key pair
    973 #    key_id: KEY_ID (fingerprint) of key pair to be deleted
    974 #
    975 # Return:
    976 #    True if succeeded
    977 #
    978 # Should return ARGUMENT_ERROR if no such key is found for user
    979 def delete_key(member_urn, key_id, credentials, options)
    980 }}}
    981 
    982 {{{
    983 #!python
    984 # Update the details of a key pair for given member
    985 #
    986 # Arguments:
    987 #    member_urn: urn of member for which to delete key pair
    988 #    key_id: KEY_ID (fingerprint) of key pair to be deleted
    989 #    options: 'fields' containing fields for key pairs that are permitted for update
    990 #
    991 # Return:
    992 #    None
    993 #
    994 # Should return ARGUMENT_ERROR if no such key is found for user
    995 def update_key(member_urn, key_id, credentials, options)
    996 }}}
    997 
    998 {{{
    999 #!python
    1000 # Lookup keys for given match criteria return fields in given filter criteria
    1001 #
    1002 # Arguments:
    1003 #    options: 'match' for query match criteria, 'filter' for fields to be returned
    1004 #
    1005 # Return:
    1006 #    Dictionary (indexed by member_urn) of dictionaries containing name/value pairs for all keys registered for that given user.
    1007 def lookup_keys(credentials, options)
    1008 }}}
    1009948
    1010949== Appendix: Federation Object Models ==