Changes between Version 54 and Version 55 of UniformClearinghouseAPI
- Timestamp:
- 08/30/13 11:11:10 (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
UniformClearinghouseAPI
v54 v55 3 3 Marshall Brinn, GPO 4 4 5 DRAFT: August 16, 20135 DRAFT: August 30, 2013 6 6 7 7 … … 80 80 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): 81 81 * 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 83 83 * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [ABAC, SFA]) and list of supported credential versions on protected API methods. 84 84 * 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). 86 86 * FIELDS: A dictionary of '''''supplementary''''' object field names (i.e. in additional to the required fields) and associated attributes including: 87 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) … … 107 107 108 108 “SERVICES”: [“SLICE”, “PROJECT”, “SLICE_MEMBER”, “PROJECT_MEMBER”], 109 110 "OBJECTS": ["SLICE", "PROJECT"], 109 111 110 112 “CREDENTIAL_TYPES”: {“SFA”: ["1"]}, “ABAC” : ["1", "2"]}, … … 130 132 131 133 “CREDENTIAL_TYPES”: [“SFA”, “ABAC”], 134 135 "SERVICES": ["MEMBER", "KEY"], 136 137 "OBJECTS": ["MEMBER", "KEY"], 132 138 133 139 “FIELDS”: { … … 429 435 430 436 Note 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 || 433 441 434 442 NB: This is an unprotected call, no client cert required. … … 589 597 function '''get_credentials'''(slice_urn, credentials, options) 590 598 591 == Slice Member Service Methods ==599 == Slice Member Service Methods == 592 600 593 601 Slices 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. … … 651 659 function '''lookup_slices_for_member'''(member_urn, credentials, options) 652 660 653 == Sliver Info Service API==661 == Sliver Info Service Methods == 654 662 655 663 Sliver 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. … … 841 849 == Member Authority API == 842 850 851 The Member Authority API provides services to manage information about federation members including public and potentially private or identifying information. 852 843 853 As 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. 844 854 … … 849 859 * 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. 850 860 * Access to private info (SSL or SSH keys) should be restricted only to the user’s own keys for ordinary users. 861 862 Like 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 == 851 869 852 870 The information managed by the MA API is divided into three categories, for purposes of applying different AuthZ policies at these different levels: … … 970 988 971 989 function '''get_credentials'''(member_urn, credentials, options) 990 991 == Key Service Methods == 992 993 The 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 995 The 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 1005 Note 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 1009 Create a record for a key pair for given member 1010 1011 '''Arguments:''' 1012 1013 member_urn: URN of member for which to retrieve credentials 1014 1015 options: 'fields' containing the fields for the key pair being stored 1016 1017 '''Return:''' 1018 1019 Dictionary of name/value pairs for created key record including the KEY_ID 1020 1021 Should return DUPLICATE_ERROR if a key with the same KEY_ID is already stored for given user 1022 1023 */ 1024 1025 function '''create_key'''(member_urn, credentials, options) 1026 1027 /* 1028 1029 Delete a key pair for given member 1030 1031 '''Arguments:''' 1032 1033 member_urn: urn of member for which to delete key pair 1034 1035 key_id: KEY_ID (fingerprint) of key pair to be deleted 1036 1037 '''Return:''' 1038 1039 True if succeeded 1040 1041 Should return ARGUMENT_ERROR if no such key is found for user 1042 1043 */ 1044 1045 function '''delete_key'''(member_urn, key_id, credentials, options) 1046 1047 /* 1048 1049 Update the details of a key pair for given member 1050 1051 '''Arguments:''' 1052 1053 member_urn: urn of member for which to delete key pair 1054 1055 key_id: KEY_ID (fingerprint) of key pair to be deleted 1056 1057 options: 'fields' containing fields for key pairs that are permitted for update 1058 1059 '''Return:''' 1060 1061 True if succeeded 1062 1063 Should return ARGUMENT_ERROR if no such key is found for user 1064 1065 */ 1066 1067 function '''update_key'''(member_urn, key_id, credentials, options) 1068 1069 /* 1070 1071 Lookup keys for given match criteria return fields in given filter criteria 1072 1073 '''Arguments:''' 1074 1075 options: 'match' for query match criteria, 'filter' for fields to be returned 1076 1077 '''Return:''' 1078 1079 Dictionary (indexed by member_urn) of dictionaries containing name/value pairs for all keys registered for that given user. 1080 1081 */ 1082 1083 function '''lookup_keys'''(credentials, options) 972 1084 973 1085 == Appendix: Federation Object Models ==