| 381 | /* |
| 382 | |
| 383 | Return information about all MA’s associated with the Federation |
| 384 | |
| 385 | NB: This is an '''unprotected''' call, no client cert required. |
| 386 | |
| 387 | '''Arguments:''' |
| 388 | |
| 389 | options: List of field names (from get_version) to be provided for each MA |
| 390 | |
| 391 | '''Return:''' |
| 392 | |
| 393 | List of dictionaries of name/value pairs for each returned MA |
| 394 | |
| 395 | */ |
| 396 | |
| 397 | function '''get_member_authorities'''(options) |
| 398 | |
| 399 | /* |
| 400 | |
| 401 | Return information about all SA’s associated with the Federation |
| 402 | |
| 403 | NB: This is an '''unprotected''' call, no client cert required. |
| 404 | |
| 405 | '''Arguments:''' |
| 406 | |
| 407 | options: List of field names (from get_version) to be provided for each SA |
| 408 | |
| 409 | '''Return:''' |
| 410 | |
| 411 | List of dictionaries of name/value pairs for each returned SA |
| 412 | |
| 413 | */ |
| 414 | |
| 415 | function '''get_slice_authorities'''(options) |
| 416 | |
| 417 | /* |
| 418 | |
| 419 | Lookup the authorities for a given URNs |
| 420 | |
| 421 | There should be at most one (potentially none) per URN |
| 422 | |
| 423 | NB: This is an unprotected call, no client cert required. |
| 424 | |
| 425 | '''Arguments:''' |
| 426 | |
| 427 | urns: URNs of entities for which the authority is requested |
| 428 | |
| 429 | '''Return:''' |
| 430 | |
| 431 | List of URL’s of Authorities corresponding, in order, to given URN’s |
| 432 | |
| 433 | */ |
| 434 | |
| 435 | function '''lookup_authorities_for_urns'''(urns) |
| 436 | |
| 437 | /* |
| 438 | |
| 439 | Return list of trust roots (certificates) associated with this CH. |
| 440 | |
| 441 | Often this is a concatenatation of the trust roots of the included authorities. |
| 442 | |
| 443 | NB: This is an '''unprotected''' call, no client cert required. |
| 444 | |
| 445 | '''Arguments:''' |
| 446 | |
| 447 | None |
| 448 | |
| 449 | '''Return:''' |
| 450 | |
| 451 | List of certificates representing trust roots of this CH. |
| 452 | |
| 453 | */ |
| 454 | |
| 455 | function '''get_trust_roots'''() |
| 456 | |
| 457 | == Slice Authority API == |
| 458 | |
| 459 | The 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 | |
| 471 | The 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 | |
| 473 | Note 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 | |
| 475 | The 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 | |
| 488 | Provide details on the version, services and options supported by this SA |
| 489 | |
| 490 | NB: This is an unprotected call, no client cert required. |
| 491 | |
| 492 | '''Arguments:''' |
| 493 | |
| 494 | Options: |
| 495 | |
| 496 | '''Return:''' |
| 497 | |
| 498 | get_version structure information as described above |
| 499 | |
| 500 | */ |
| 501 | |
| 502 | function '''get_version()''' |
| 503 | |
| 504 | /* |
| 505 | |
| 506 | Create a new slice, optionally within a project. See generic create_* method description above. |
| 507 | |
| 508 | '''Arguments:''' |
| 509 | |
| 510 | Options: Contains field/value pairs for object to be created |
| 511 | |
| 512 | slice_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 | |
| 518 | function '''create_slice''' (credentials, options) |
| 519 | |
| 520 | /* |
| 521 | |
| 522 | Lookup 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:''' |
| 527 | options: 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 | |
| 533 | function '''lookup_slices''' (credentials, options) |
| 534 | |
| 535 | /* |
| 536 | |
| 537 | Update fields in given slice object. See generic update_* method description above. |
| 538 | |
| 539 | '''Arguments:''' |
| 540 | |
| 541 | slice_urn: URN of slice to update |
| 542 | |
| 543 | Options: Contains ‘update’ key referring dictionary of name/value pairs to update |
| 544 | |
| 545 | '''Return:''' None |
| 546 | |
| 547 | */ |
| 548 | |
| 549 | function '''update_slice'''(slice_urn, credentials, options) |
| 550 | |
| 551 | /* |
| 552 | |
| 553 | Provide 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 | |
| 555 | For 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 | |
| 559 | slice_urn: URN of slice for which to get member’s credentials |
| 560 | |
| 561 | options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument) |
| 562 | |
| 563 | '''Return:''' |
| 564 | |
| 565 | List 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 | |
| 569 | function '''get_credentials'''(slice_urn, credentials, options) |
| 570 | |
| 571 | ==Slice Member Service Methods == |
| 572 | |
| 573 | Slices 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 | |
| 575 | The 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 | |
| 579 | Modify slice membership, adding, removing and changing roles of members with respect to given slice |
| 580 | |
| 581 | '''Arguments:''' |
| 582 | |
| 583 | Slice_urn: URN of slice for which to modify membership |
| 584 | |
| 585 | '''Options:''' |
| 586 | |
| 587 | members_to_add: List of member_urn/role tuples for members to add to slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role} |
| 588 | |
| 589 | members_to_remove: List of member_urn of members to remove from slice |
| 590 | |
| 591 | members_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 | |
| 595 | None |
| 596 | |
| 597 | */ |
| 598 | |
| 599 | function '''modify_slice_membership''' (slice_urn, credentials, options) |
| 600 | |
| 601 | /* |
| 602 | |
| 603 | Lookup members of given slice and their roles within that slice |
| 604 | |
| 605 | '''Arguments:''' |
| 606 | |
| 607 | slice_urn: URN of slice for which to provide current members and roles |
| 608 | |
| 609 | '''Return:''' |
| 610 | |
| 611 | Dictionary of member_urn/role pairs {‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role } where ‘role’ is a string of the role name |
| 612 | |
| 613 | */ |
| 614 | |
| 615 | function '''lookup_slice_members''' (slice_urn, credentials, options) |
| 616 | |
| 617 | /* |
| 618 | |
| 619 | Lookup slices for which the given member belongs |
| 620 | |
| 621 | '''Arguments:''' |
| 622 | |
| 623 | Member_urn: The member for whom to find slices to which it belongs |
| 624 | |
| 625 | '''Return:''' |
| 626 | |
| 627 | Dictionary of slice_urn/role pairs (‘SLICE_URN’ : slice_urn, ‘SLICE_ROLE’ : role} where role is a string of the role name |
| 628 | |
| 629 | */ |
| 630 | |
| 631 | function lookup_slices_for_member(member_urn, credentials, options) |
| 632 | |
| 633 | == Sliver Info Service API == |
| 634 | |
| 635 | 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. |
| 636 | |
| 637 | /* |
| 638 | |
| 639 | Associate an aggregate as having sliver information in a given slice |
| 640 | Expected to be called by an aggregate as an asynchronous (not critical-path) part of the resource allocation process. |
| 641 | |
| 642 | */ |
| 643 | |
| 644 | '''Arguments:''' |
| 645 | |
| 646 | slice_urn: URN of slice for which to associate aggregate |
| 647 | |
| 648 | aggregate_url : URL of aggregate for which slivers may exist for the given slice |
| 649 | |
| 650 | '''Return:''' |
| 651 | |
| 652 | None |
| 653 | |
| 654 | function register_aggregate(slice_urn, aggregate_url, credentials, options) |
| 655 | |
| 656 | /* |
| 657 | |
| 658 | Dis-associate an aggregate as having sliver information in a given slice |
| 659 | |
| 660 | Expected 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 | |
| 666 | slice_urn: URN of slice for which to associate aggregate |
| 667 | |
| 668 | aggregate_url : URL of aggregate for which slivers may exist for the given slice |
| 669 | |
| 670 | '''Return:''' |
| 671 | |
| 672 | None |
| 673 | |
| 674 | function '''remove_aggregate'''(slice_urn, aggregate_url, credentials, options) |
| 675 | |
| 676 | /* |
| 677 | |
| 678 | Provide a list of URLs of all aggregates that have been registered as having resources allocated with a given slice. |
| 679 | |
| 680 | NB: 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 | |
| 684 | slice_urn: URN of slice for which to return associated aggregates |
| 685 | |
| 686 | '''Return:''' |
| 687 | |
| 688 | List of URL’s of aggregates for which slivers may exist for given slice. |
| 689 | |
| 690 | */ |
| 691 | |
| 692 | function '''get_slice_aggregates'''(slice_urn, credentials, options) |
| 693 | |
| 694 | == Project Service Methods == |
| 695 | |
| 696 | Projects 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 | |
| 698 | The 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 | |
| 711 | Create project with given details. See generic create_* description above. |
| 712 | |
| 713 | '''Arguments:''' |
| 714 | |
| 715 | Options: Dictionary of name/value pairs for newly created project. |
| 716 | |
| 717 | '''Return:''' |
| 718 | |
| 719 | Dictionary of name/value pairs of newly created project including urn |
| 720 | |
| 721 | */ |
| 722 | |
| 723 | function '''create_project'''(credentials, options) |
| 724 | |
| 725 | /* |
| 726 | |
| 727 | Lookup project detail for projects matching ‘match options. |
| 728 | |
| 729 | ‘filter options indicate what detail to provide. |
| 730 | |
| 731 | '''Arguments:''' |
| 732 | |
| 733 | options: 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 | |
| 739 | function '''lookup_projects''' (credentials, options) |
| 740 | |
| 741 | /* |
| 742 | |
| 743 | Update fields in given project object, as allowed in Get_version advertisement. See generic update_* description above. |
| 744 | |
| 745 | '''Arguments:''' |
| 746 | |
| 747 | project_urn: URN of project to update |
| 748 | |
| 749 | Options: Contains ‘update’ key referencing dictionary of key/value pairs to update project |
| 750 | ''' |
| 751 | Return:''' None |
| 752 | |
| 753 | */ |
| 754 | |
| 755 | function '''update_project'''(project_urn, credentials, options) |
| 756 | |
| 757 | == Project Member Service Methods == |
| 758 | |
| 759 | Projects may have members associated with them in particular roles. See the Slice Member Service Methods above for more description. |
| 760 | |
| 761 | /* |
| 762 | |
| 763 | Modify project membership, adding, removing and changing roles of members with respect to given project |
| 764 | ''' |
| 765 | Arguments:''' |
| 766 | |
| 767 | project_urn: Name of project for which to modify membership |
| 768 | |
| 769 | '''Options:''' |
| 770 | |
| 771 | members_to_add: List of member_urn/role tuples for members to add to project of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’ : role} |
| 772 | |
| 773 | members_to_remove: List of member_urn of members to remove from project |
| 774 | |
| 775 | members_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 | ''' |
| 777 | Return:''' |
| 778 | |
| 779 | None |
| 780 | |
| 781 | */ |
| 782 | |
| 783 | function modify_project_membership (project_urn, credentials, options) |
| 784 | |
| 785 | /* |
| 786 | |
| 787 | Lookup members of given project and their roles within that project |
| 788 | |
| 789 | '''Arguments:''' |
| 790 | |
| 791 | project_urn: project_urn for which to provide current members and roles |
| 792 | |
| 793 | '''Return:''' |
| 794 | |
| 795 | Dictionary of member_urn/role pairs of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’: role} |
| 796 | |
| 797 | */ |
| 798 | |
| 799 | function '''lookup_project_members''' (project_urn, credentials, options) |
| 800 | |
| 801 | /* |
| 802 | |
| 803 | Lookup projects for which the given member belongs |
| 804 | |
| 805 | '''Arguments:''' |
| 806 | |
| 807 | Member_urn: The member for whom to find project to which it belongs |
| 808 | |
| 809 | '''Return:''' |
| 810 | |
| 811 | Dictionary of slice_urn/role pairs (‘PROJECT_URN’ : project_urn, ‘PROJECT_ROLE’ : role} where role is a string of the role name |
| 812 | |
| 813 | */ |
| 814 | |
| 815 | function lookup_projects_for_member(member_urn, credentials, options) |
| 816 | |
| 817 | == Member Authority API == |
| 818 | |
| 819 | As 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 | |
| 821 | The 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 | |
| 827 | The 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 | |