Changes between Version 54 and Version 55 of UniformClearinghouseAPI


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

Add documentation for MA KEY service

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPI

    v54 v55  
    33Marshall Brinn, GPO
    44
    5 DRAFT: August 16, 2013
     5DRAFT: August 30, 2013
    66
    77
     
    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)
     
    107107
    108108“SERVICES”: [“SLICE”, “PROJECT”, “SLICE_MEMBER”, “PROJECT_MEMBER”],
     109
     110"OBJECTS": ["SLICE", "PROJECT"],
    109111
    110112“CREDENTIAL_TYPES”: {“SFA”: ["1"]}, “ABAC” : ["1", "2"]},
     
    130132
    131133      “CREDENTIAL_TYPES”: [“SFA”, “ABAC”],
     134
     135      "SERVICES": ["MEMBER", "KEY"],
     136
     137      "OBJECTS": ["MEMBER", "KEY"],
    132138
    133139      “FIELDS”: {
     
    429435
    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
     437
     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 ||
    433441
    434442NB: This is an unprotected call, no client cert required.
     
    589597function '''get_credentials'''(slice_urn, credentials, options)
    590598
    591 ==Slice Member Service Methods ==
     599== Slice Member Service Methods ==
    592600
    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)
    652660
    653 == Sliver Info Service API ==
     661== Sliver Info Service Methods ==
    654662
    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 ==
    842850
     851The Member Authority API provides services to manage information about federation members including public and potentially private or identifying information.
     852
    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.
    844854
     
    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.
     861
     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:
     863
     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 ||
     867
     868== Member Service Methods ==
    851869
    852870The information managed by the MA API is divided into three categories, for purposes of applying different AuthZ policies at these different levels:
     
    970988
    971989function '''get_credentials'''(member_urn, credentials, options)
     990
     991== Key Service Methods ==
     992
     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.
     994
     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:
     996
     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 ||
     1004
     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.
     1006
     1007/*
     1008
     1009Create a record for a key pair for given member
     1010
     1011'''Arguments:'''
     1012
     1013member_urn: URN of member for which to retrieve credentials
     1014
     1015options: 'fields' containing the fields for the key pair being stored
     1016
     1017'''Return:'''
     1018
     1019Dictionary of name/value pairs for created key record including the KEY_ID
     1020
     1021Should return DUPLICATE_ERROR if a key with the same KEY_ID is already stored for given user
     1022
     1023*/
     1024
     1025function '''create_key'''(member_urn, credentials, options)
     1026
     1027/*
     1028
     1029Delete a key pair for given member
     1030
     1031'''Arguments:'''
     1032
     1033member_urn: urn of member for which to delete key pair
     1034
     1035key_id: KEY_ID (fingerprint) of key pair to be deleted
     1036
     1037'''Return:'''
     1038
     1039True if succeeded
     1040
     1041Should return ARGUMENT_ERROR if no such key is found for user
     1042
     1043*/
     1044
     1045function '''delete_key'''(member_urn, key_id, credentials, options)
     1046
     1047/*
     1048
     1049Update the details of a key pair for given member
     1050
     1051'''Arguments:'''
     1052
     1053member_urn: urn of member for which to delete key pair
     1054
     1055key_id: KEY_ID (fingerprint) of key pair to be deleted
     1056
     1057options: 'fields' containing fields for key pairs that are permitted for update
     1058
     1059'''Return:'''
     1060
     1061True if succeeded
     1062
     1063Should return ARGUMENT_ERROR if no such key is found for user
     1064
     1065*/
     1066
     1067function '''update_key'''(member_urn, key_id, credentials, options)
     1068
     1069/*
     1070
     1071Lookup keys for given match criteria return fields in given filter criteria
     1072
     1073'''Arguments:'''
     1074
     1075options: 'match' for query match criteria, 'filter' for fields to be returned
     1076
     1077'''Return:'''
     1078
     1079Dictionary (indexed by member_urn) of dictionaries containing name/value pairs for all keys registered for that given user.
     1080
     1081*/
     1082
     1083function '''lookup_keys'''(credentials, options)
    9721084
    9731085== Appendix: Federation Object Models ==