Changes between Version 54 and Version 55 of UniformClearinghouseAPI

08/30/13 11:11:10 (6 years ago)

Add documentation for MA KEY service


  • UniformClearinghouseAPI

    v54 v55  
    33Marshall Brinn, GPO
    5 DRAFT: August 16, 2013
     5DRAFT: August 30, 2013
    8080Each 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”)
    82  * SERVICES: The set of services the given URL supports (only for Slice Authority)
     82 * SERVICES: The set of services the given URL supports
    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 Registry).
     85 * OBJECTS : List of additional supported objects (e.g. PROJECT in SA, KEY in MA). Not needed if only defaiit objects handled (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:
    8787     * “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)
     110"OBJECTS": ["SLICE", "PROJECT"],
    110112“CREDENTIAL_TYPES”: {“SFA”: ["1"]}, “ABAC” : ["1", "2"]},
    131133      “CREDENTIAL_TYPES”: [“SFA”, “ABAC”],
     135      "SERVICES": ["MEMBER", "KEY"],
     137      "OBJECTS": ["MEMBER", "KEY"],
    133139      “FIELDS”: {
    430436Note that the transformation from the URN's of objects (e.g. slice, project, member) to the URN's of their authority is a simple one, for example:
    431  * Slice: urn:publicid:IDN+sa_name+slice+slice_name => SA : urn:publicid:IDN+sa_name+authority+sa
    432  * Member : urn:publicid:IDN+ma_name+user+user_name => MA: urn:publicid:IDN+ma_name+authority+ma
     438|| '''Type''' || '''Object URN''' || '''Authority URN''' ||
     439|| Slice || urn:publicid:IDN+sa_name+slice+slice_name || urn:publicid:IDN+sa_name+authority+sa ||
     440|| Member || urn:publicid:IDN+ma_name+user+user_name || urn:publicid:IDN+ma_name+authority+ma ||
    434442NB: This is an unprotected call, no client cert required.
    589597function '''get_credentials'''(slice_urn, credentials, options)
    591 ==Slice Member Service Methods ==
     599== Slice Member Service Methods ==
    593601Slices 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.
    651659function '''lookup_slices_for_member'''(member_urn, credentials, options)
    653 == Sliver Info Service API ==
     661== Sliver Info Service Methods ==
    655663Sliver information is authoritatively held in aggregates: aggregates know which slivers are in which slices at that aggregate. As a convenience to tools, aggregates are encouraged to register with the SA which slices they have information about. In this way, tools can reference only certain aggregates and not all known aggregates to get a useful (if not authoritative) set of sliver details for a slice.
    841849== Member Authority API ==
     851The Member Authority API provides services to manage information about federation members including public and potentially private or identifying information.
    843853As 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.
    849859 * 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.
    850860 * Access to private info (SSL or SSH keys) should be restricted only to the user’s own keys for ordinary users.
     862Like the Slice Authority, he Member Authority provides a set of services each consisting of a set of methods. Some services are required for any MA implementation, others are optional, as indicated by this table:
     864|| '''Service''' || '''Description''' || '''Required''' ||
     865|| MEMBER || Services to  lookup and update information about members || YES ||
     866|| KEY || Services to support storing, deleting and retrieving keys (e.g. SSH)  for members || NO ||
     868== Member Service Methods ==
    852870The information managed by the MA API is divided into three categories, for purposes of applying different AuthZ policies at these different levels:
    971989function '''get_credentials'''(member_urn, credentials, options)
     991== Key Service Methods ==
     993The Key Service provides methods to allow for storing, deleting and retrieving SSH or similar keys for members. It is not intended for retrieving SSL public/private keys or certs.
     995The following table contains the required fields for key objects and whether they are allowed in lookup 'match' criteria, required at creation or allowed at update:
     997|| '''Name''' || '''Type''' || '''Description''' || '''Match''' || '''Creation''' || '''Update''' ||
     998|| KEY_MEMBER || URN || URN of member associated with key pair || Yes || Required || No ||
     999|| KEY_TYPE || STRING || Type of  Key (RSA, DSA, etc.) || Yes || Allowed || Yes ||
     1000|| KEY_ID || STRING || Unique identifier of key: typically a fingerprint or hash of public key || Yes || No || No ||
     1001|| KEY_PUBLIC || KEY || Public key value || Yes || Required || No ||
     1002|| KEY_PRIVATE || KEY || Private key value || Yes || Allowed || No ||
     1003|| KEY_DESCRIPTION || STRING || Human readable description of key pair || Yes || Allowed || Yes ||
     1005Note 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.
     1009Create a record for a key pair for given member
     1013member_urn: URN of member for which to retrieve credentials
     1015options: 'fields' containing the fields for the key pair being stored
     1019Dictionary of name/value pairs for created key record including the KEY_ID
     1021Should return DUPLICATE_ERROR if a key with the same KEY_ID is already stored for given user
     1025function '''create_key'''(member_urn, credentials, options)
     1029Delete a key pair for given member
     1033member_urn: urn of member for which to delete key pair
     1035key_id: KEY_ID (fingerprint) of key pair to be deleted
     1039True if succeeded
     1041Should return ARGUMENT_ERROR if no such key is found for user
     1045function '''delete_key'''(member_urn, key_id, credentials, options)
     1049Update the details of a key pair for given member
     1053member_urn: urn of member for which to delete key pair
     1055key_id: KEY_ID (fingerprint) of key pair to be deleted
     1057options: 'fields' containing fields for key pairs that are permitted for update
     1061True if succeeded
     1063Should return ARGUMENT_ERROR if no such key is found for user
     1067function '''update_key'''(member_urn, key_id, credentials, options)
     1071Lookup keys for given match criteria return fields in given filter criteria
     1075options: 'match' for query match criteria, 'filter' for fields to be returned
     1079Dictionary (indexed by member_urn) of dictionaries containing name/value pairs for all keys registered for that given user.
     1083function '''lookup_keys'''(credentials, options)
    9731085== Appendix: Federation Object Models ==