Changes between Version 14 and Version 15 of UniformClearinghouseAPI


Ignore:
Timestamp:
08/15/13 11:44:01 (11 years ago)
Author:
jmccolga@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPI

    v14 v15  
    379379function '''get_aggregates'''(options)
    380380
     381/*
     382
     383Return information about all MA’s associated with the Federation
     384
     385NB: This is an '''unprotected''' call, no client cert required.
     386
     387'''Arguments:'''
     388
     389options: List of field names (from get_version) to be provided for each MA
     390
     391'''Return:'''
     392
     393List of dictionaries of name/value pairs for each returned MA
     394
     395*/
     396
     397function '''get_member_authorities'''(options)
     398
     399/*
     400
     401Return information about all SA’s associated with the Federation
     402
     403NB: This is an '''unprotected''' call, no client cert required.
     404
     405'''Arguments:'''
     406
     407options: List of field names (from get_version) to be provided for each SA
     408
     409'''Return:'''
     410
     411List of dictionaries of name/value pairs for each returned SA
     412
     413*/
     414
     415function '''get_slice_authorities'''(options)
     416
     417/*
     418
     419Lookup the authorities for a given URNs
     420
     421There should be at most one (potentially none) per URN
     422
     423NB: This is an unprotected call, no client cert required.
     424
     425'''Arguments:'''
     426
     427urns: URNs of entities for which the authority is requested
     428
     429'''Return:'''
     430
     431List of URL’s of Authorities corresponding, in order, to given URN’s
     432
     433*/
     434
     435function '''lookup_authorities_for_urns'''(urns)
     436
     437/*
     438
     439Return list of trust roots (certificates) associated with this CH.
     440
     441Often this is a concatenatation of the trust roots of the included authorities.
     442
     443NB: This is an '''unprotected''' call, no client cert required.
     444
     445'''Arguments:'''
     446
     447None
     448
     449'''Return:'''
     450
     451List of certificates representing trust roots of this CH.
     452
     453*/
     454
     455function '''get_trust_roots'''()
     456
     457== Slice Authority API ==
     458
     459The Slice Authority API provides services to manage slices and their associated permissions. To support its AuthZ policies, a particular SA may choose to manage objects and relationships such as projects and slice/project membership. The SA API is thus divided into a set of services, each of which consists of a set of methods. Of these, only the SLICE service is required, the others are optional. If an SA implements a given service, it should implement the entire service as specified. All available SA service methods are available form the same SA URL. The get_version method should indicate, in the ‘SERVICES’ tag, which services the given SA supports. The following is a list of potential SA services.
     460
     461
     462|| ''' Service ''' || ''' Description ''' || ''' Required ''' ||
     463|| SLICE || Managing generation, renewal of slice credentials and slice lookup services || YES ||
     464|| SLICE_MEMBER ||Defining and managing roles of members with respect to slices || NO ||
     465|| SLIVER_INFO || Providing information about what Aggregates have reported having slivers for a given slice. Non-authoritative/advisory || NO ||
     466|| PROJECT || Defining projects (groupings of slices) and project lookup services || NO ||
     467|| PROJECT_MEMBER || Defining and managing roles of members with respect to projects || NO ||
     468
     469== Slice Service Methods ==
     470
     471The 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.
     472
     473Note 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.
     474
     475The following table contains required fields for slice objects and whether they are allowed in lookup ‘match’ criteria, required at creation or allowed at update:
     476
     477|| ''' Name ''' || ''' Type ''' || ''' Description ''' || ''' Match ''' || ''' Creation ''' || ''' Update ''' ||
     478|| SLICE_URN || URN || URN of given slice || Yes || No || No ||
     479|| SLICE_UID ||UID || UID (unique within authority) of slice || Yes || No || No ||
     480|| SLICE_CREATION || DATETIME || Creation time of slice || No || No || No ||
     481|| SLICE_EXPIRATION || DATETIME || Expiration time of slice || No || Allowed || Yes ||
     482|| EXPIRED || BOOLEAN || Whether slice has expired || Yes || No || No ||
     483|| SLICE_NAME || STRING || Short name of Slice || No || Required || No ||
     484|| SLICE_DESCRIPTION || STRING || Description of Slice || No || Allowed || Yes ||
     485
     486/*
     487
     488Provide details on the version, services and options supported by this SA
     489
     490NB: This is an unprotected call, no client cert required.
     491
     492'''Arguments:'''
     493
     494Options:
     495
     496'''Return:'''
     497
     498get_version structure information as described above
     499
     500*/
     501
     502function '''get_version()'''
     503
     504/*
     505
     506Create a new slice, optionally within a project. See generic create_* method description above.
     507
     508'''Arguments:'''
     509
     510Options: Contains field/value pairs for object to be created
     511
     512slice_name: Name of slice to create
     513
     514'''Return:''' Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
     515
     516*/
     517
     518function '''create_slice''' (credentials, options)
     519
     520/*
     521
     522Lookup slice detail for slices matching ‘match’ options.
     523
     524‘filter’ options indicate what detail to provide. See generic lookup_* method description above.
     525
     526'''Arguments:'''
     527options: What details to provide (filter options) for which slices (match options)
     528
     529'''Return:''' List of dictionaries with slice field/value pairs
     530
     531*/
     532
     533function '''lookup_slices''' (credentials, options)
     534
     535/*
     536
     537Update fields in given slice object. See generic update_* method description above.
     538
     539'''Arguments:'''
     540
     541slice_urn: URN of slice to update
     542
     543Options: Contains ‘update’ key referring dictionary of name/value pairs to update
     544
     545'''Return:''' None
     546
     547*/
     548
     549function '''update_slice'''(slice_urn, credentials, options)
     550
     551/*
     552
     553Provide list of credentials for the invoking member relative to the given slice. If the invocation is in a speaks-for context, the credentials will be for the ‘spoken-for’ member, not the invoking tool.
     554
     555For example, this call may return a standard SFA Slice Credential and some ABAC credentials indicating the role of the member with respect to the slice.
     556
     557'''Arguments:'''
     558
     559slice_urn: URN of slice for which to get member’s credentials
     560
     561options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
     562
     563'''Return:'''
     564
     565List of credential in “CREDENTIAL_LIST” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
     566
     567*/
     568
     569function '''get_credentials'''(slice_urn, credentials, options)
     570
     571==Slice Member Service Methods ==
     572
     573Slices 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.
     574
     575The 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.
     576
     577/*
     578
     579Modify slice membership, adding, removing and changing roles of members with respect to given slice
     580
     581'''Arguments:'''
     582
     583Slice_urn: URN of slice for which to modify membership
     584
     585'''Options:'''
     586
     587members_to_add: List of member_urn/role tuples for members to add to slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
     588
     589members_to_remove: List of member_urn of members to remove from slice
     590
     591members_to_change: List of member_urn/role tuples for members whose role should change as specified for given slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
     592
     593'''Return:'''
     594
     595None
     596
     597*/
     598
     599function '''modify_slice_membership''' (slice_urn, credentials, options)
     600
     601/*
     602
     603Lookup members of given slice and their roles within that slice
     604
     605'''Arguments:'''
     606
     607slice_urn: URN of slice for which to provide current members and roles
     608
     609'''Return:'''
     610
     611Dictionary of member_urn/role pairs {‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role } where ‘role’ is a string of the role name
     612
     613*/
     614
     615function '''lookup_slice_members''' (slice_urn, credentials, options)
     616
     617/*
     618
     619Lookup slices for which the given member belongs
     620
     621'''Arguments:'''
     622
     623Member_urn: The member for whom to find slices to which it belongs
     624
     625'''Return:'''
     626
     627Dictionary of slice_urn/role pairs (‘SLICE_URN’ : slice_urn, ‘SLICE_ROLE’ : role} where role is a string of the role name
     628
     629*/
     630
     631function lookup_slices_for_member(member_urn, credentials, options)
     632
     633== Sliver Info Service API ==
     634
     635Sliver 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.
     636
     637/*
     638
     639Associate an aggregate as having sliver information in a given slice
     640Expected to be called by an aggregate as an asynchronous (not critical-path) part of the resource allocation process.
     641
     642*/
     643
     644'''Arguments:'''
     645
     646slice_urn: URN of slice for which to associate aggregate
     647
     648aggregate_url : URL of aggregate for which slivers may exist for the given slice
     649
     650'''Return:'''
     651
     652None
     653
     654function register_aggregate(slice_urn, aggregate_url, credentials, options)
     655
     656/*
     657
     658Dis-associate an aggregate as having sliver information in a given slice
     659
     660Expected to be called by an aggregate as an asynchronous (not critical-path) part of the resource de-allocation process.
     661
     662*/
     663
     664'''Arguments:'''
     665
     666slice_urn: URN of slice for which to associate aggregate
     667
     668aggregate_url : URL of aggregate for which slivers may exist for the given slice
     669
     670'''Return:'''
     671
     672None
     673
     674function '''remove_aggregate'''(slice_urn, aggregate_url, credentials, options)
     675
     676/*
     677
     678Provide a list of URLs of all aggregates that have been registered as having resources allocated with a given slice.
     679
     680NB: 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).
     681
     682'''Arguments:'''
     683
     684slice_urn: URN of slice for which to return associated aggregates
     685
     686'''Return:'''
     687
     688List of URL’s of aggregates for which slivers may exist for given slice.
     689
     690*/
     691
     692function '''get_slice_aggregates'''(slice_urn, credentials, options)
     693
     694== Project Service Methods ==
     695
     696Projects 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.
     697
     698The following table contains required fields for project objects and whether they are allowed in lookup ‘match’ criteria, required at creation or allowed at update:
     699
     700|| ''' Name ''' || ''' Type ''' || ''' Description ''' || ''' Match ''' || ''' Creation ''' || ''' Update ''' ||
     701|| PROJECT_URN || URN || URN of given project || Yes || No || No ||
     702|| PROJECT_UID ||UID || UID (unique within authority) of project || Yes || No || No ||
     703|| PROJECT_CREATION || DATETIME || Creation time of project || No || No || No ||
     704|| PROJECT_EXPIRATION || DATETIME || Expiration time of project || No || Allowed || Yes ||
     705|| EXPIRED || BOOLEAN || Whether project has expired || Yes || No || No ||
     706|| PROJECT_NAME || STRING || Short name of Project || No || Required || No ||
     707|| PROJECT_DESCRIPTION || STRING || Description of Project || No || Allowed || Yes ||
     708
     709/*
     710
     711Create project with given details. See generic create_* description above.
     712
     713'''Arguments:'''
     714
     715Options: Dictionary of name/value pairs for newly created project.
     716
     717'''Return:'''
     718
     719Dictionary of name/value pairs of newly created project including urn
     720
     721*/
     722
     723function '''create_project'''(credentials, options)
     724
     725/*
     726
     727Lookup project detail for projects matching ‘match options.
     728
     729‘filter options indicate what detail to provide.
     730
     731'''Arguments:'''
     732
     733options: What details to provide (filter options) for which members (match options)
     734
     735'''Return:''' Dictionary of name/value pairs from ‘filter’ options for each project matching ‘match’ option criteria.
     736
     737*/
     738
     739function '''lookup_projects''' (credentials, options)
     740
     741/*
     742
     743Update fields in given project object, as allowed in Get_version advertisement. See generic update_* description above.
     744
     745'''Arguments:'''
     746
     747project_urn: URN of project to update
     748
     749Options: Contains ‘update’ key referencing dictionary of key/value pairs to update project
     750'''
     751Return:''' None
     752
     753*/
     754
     755function '''update_project'''(project_urn, credentials, options)
     756
     757== Project Member Service Methods ==
     758
     759Projects may have members associated with them in particular roles. See the Slice Member Service Methods above for more description.
     760
     761/*
     762
     763Modify project membership, adding, removing and changing roles of members with respect to given project
     764'''
     765Arguments:'''
     766
     767project_urn: Name of project for which to modify membership
     768
     769'''Options:'''
     770
     771members_to_add: List of member_urn/role tuples for members to add to project of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’ : role}
     772
     773members_to_remove: List of member_urn of members to remove from project
     774
     775members_to_change: List of member_urn/role tuples for members whose role should change as specified for given project of form {‘PROJECT_MEMBER’ : member_urn, ‘PROJECT_ROLE’ : role}
     776'''
     777Return:'''
     778
     779None
     780
     781*/
     782
     783function modify_project_membership (project_urn, credentials, options)
     784
     785/*
     786
     787Lookup members of given project and their roles within that project
     788
     789'''Arguments:'''
     790
     791project_urn: project_urn for which to provide current members and roles
     792
     793'''Return:'''
     794
     795Dictionary of member_urn/role pairs of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’: role}
     796
     797*/
     798
     799function '''lookup_project_members''' (project_urn, credentials, options)
     800
     801/*
     802
     803Lookup projects for which the given member belongs
     804
     805'''Arguments:'''
     806
     807Member_urn: The member for whom to find project to which it belongs
     808
     809'''Return:'''
     810
     811Dictionary of slice_urn/role pairs (‘PROJECT_URN’ : project_urn, ‘PROJECT_ROLE’ : role} where role is a string of the role name
     812
     813*/
     814
     815function lookup_projects_for_member(member_urn, credentials, options)
     816
     817== Member Authority API ==
     818
     819As 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.
     820
     821The 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:
     822• The user/tool cert is signed by someone in the CH’s trust chain
     823• 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.
     824• 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.
     825• Access to private info (SSL or SSH keys) should be restricted only to the user’s own keys for ordinary users.
     826
     827The information managed by the MA API is divided into three categories, for purposes of applying different AuthZ policies at these different levels:
     828• Public: Public information about a member (e.g. public SSH or SSH keys, speaks-for credentials, certificates)
     829• Private: Private information (e.g. private SSL or SSH keys) that should be given only to the member or a tool speaking for the member with a valid speaks-for credential
     830• Identifying: Information that could identify the given member (e.g. name, email, affiliation)
     831
     832
     833