Changes between Version 2 and Version 3 of GeniApiIdentifiers


Ignore:
Timestamp:
04/19/12 09:48:01 (12 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GeniApiIdentifiers

    v2 v3  
    66
    77=== Public Identifiers ===
    8 GENI URNs are in the [http://www.faqs.org/rfcs/rfc3151.html URN namespace for Public Identifiers].  As such, each GENI URN is of the form: urn:publicid:{transcribed-public-identifier}.  [http://www.faqs.org/rfcs/rfc3151.html RFC 3151] describes how public identifiers are transcribed to URNs (which involves collapsing whitespace and replacing certain characters with % encoded values). 
     8GENI URNs are in the [http://www.faqs.org/rfcs/rfc3151.html URN namespace for Public Identifiers].  As such, each GENI URN is of the form: `urn:publicid:{transcribed-public-identifier}`.  [http://www.faqs.org/rfcs/rfc3151.html RFC 3151] describes how public identifiers are transcribed to URNs (which involves collapsing whitespace and replacing certain characters with `%` encoded values). 
    99
    1010The public identifier section of a GENI URN must begin with "IDN ".  When transcribed, this means that all GENI URNs begin with "urn:publicid:IDN+". 
    … …  
    3535
    3636
     37Formally, the URN format follows the following naming convention (in perl regular expression syntax for the encoding string):
     38 `“IDN [toplevelauthority][\/\/sub-authority]* resource-type resource-name”`
    3739
     40This would lead to the following urn schema in the public id namespace (Using the transformation in [http://www.faqs.org/rfcs/rfc3151.html RFC 3151] :
     41 `“urn:publicid:IDN+toplevelauthority[:sub-authority]*\+resource-type\+resource-name”`
     42
     43Where:
     44
     45''toplevelauthority''
     46 is an internationalized domain name (which must match the one in the certificate of the authority which issued the object name)
     47''sub-authority''
     48 is an internationalized domain name (which must match the one in the certificate of the authority which issued the object name)
     49''resource-type''
     50 is a string describing the type of the named object (the set of strings is described below)
     51''resource-name''
     52 should uniquely identify the object among any other resources with identical ''toplevelauthority'' and ''resource-type''. It is important to realize that the GENI API attaches no other significance to this field, and in particular, no relation is implied between objects with identical ''resource-name'' but differing ''toplevelauthority'' or ''resource-type''. However, individual authorities may choose to define additional semantics for resource names.
    3853
    3954=== Examples and Usage ===
    4055
    41 An example: urn:publicid:IDN+geni:gpo:gcf+user+joe
     56The following examples are borrowed from the GMOC Proposal:
    4257
     58|| '''Resource''' || '''GENI Identifier''' ||
     59|| User `cviecco` at the planetlab namespace || `urn:publicid:IDN+planet-lab.org+user+cviecco` ||
     60|| Planetlab node: `pl2.ucs.indiana.edu` || `urn:publicid:IDN+planet-lab.org+node+pl2.ucs.indiana.edu` ||
     61|| Interface `eth0` in planetlab node `pl1.ucs.indiana.edu` || `urn:publicid:IDN+planet-lab.org+interface+pl1.ucs.indiana.edu:eth0` ||
     62
     63Examples of additional types of objects from the ProtoGENI documentation:
     64
     65|| '''Resource''' || '''GENI Identifier''' ||
     66|| Slice `mytestslice` in the Utah Emulab slice authority || `urn:publicid:IDN+emulab.net+slice+mytestslice` ||
     67|| The Utah Emulab slice authority || `urn:publicid:IDN+emulab.net+authority+sa` ||
     68|| Sliver `123` in the Utah Emulab aggregate manager || `urn:publicid:IDN+emulab.net+sliver+123` ||
    4369
    4470In the GENI API, URNs are used to name slices (as seen as arguments in GENI API calls), to identify users, and to label resources.  URNs are also used in GENI certificates (to bind public keys to identifiers) and in Credentials (to grant permissions to source identifiers on target identifiers). 
    4571
    4672
    47 
    48 
    49 
    50 
    5173=== Authority String ===
    52 Authorities are resource namespaces.  For instance, 'plc' is the overall PlanetLab namespace and 'plc.princeton' and 'plc.bbn' are specific namespaces for the Princeton and BBN PlanetLab sites.  The authority string format is 'toplevelauthority:sub_authority1:...:sub_authority_n.  Only entities with URNs of type 'authority' are allowed to sign credentials for a namespace (except in the case of delegation).
     74Authorities are resource namespaces.  For instance, 'plc' is the overall PlanetLab namespace and 'plc.princeton' and 'plc.bbn' are specific namespaces for the Princeton and BBN PlanetLab sites.  The authority string format is `toplevelauthority:sub_authority1:...:sub_authority_n`.  Only entities with URNs of type `authority` are allowed to sign credentials for a namespace (except in the case of delegation).
    5375
    5476For example, a ProtoGENI Clearinghouse with URN like protogeni.utah.... cannot issue a slice credential giving a user privileges on a PlanetLab slice (with urn plc.princeton....). Only PlanetLab can grant rights over PlanetLab slices.
    … …  
    5678
    5779=== Type ===
    58 The <type> string has not yet been completely specified.  Existing types in use include user, authority, switch, node, sliver, ticket, and interface.  Please try to use the available types unless they simply do not fit for you.  In which case, please contact the GPO to inform them of your new type.
     80The <type> string has not yet been completely specified, but is used to identify the kind of resource being identified. Many APIs require use of URNs with particular types.  Use the defined types below, unless they simply do not fit for you.  In which case, please contact the GPO to inform them of your new type.
    5981
     82`authority`
     83 A GENI service (i.e. an XMLRPC server). By convention, `resource-name` is am for an aggregate manager, sa for a slice authority. In principle, other names could be used for authorities.
     84`interface`
     85 A component which is an interface (an endpoint for links). The `toplevelauthority` must match that of the aggregate manager.
     86`link`
     87 A component which is a network link (a connection between two or more interfaces). The `toplevelauthority` must match that of the aggregate manager.
     88`node`
     89 A component which is a node (an abstraction for networkable resources). The `toplevelauthority` must match that of the aggregate manager.
     90`slice`
     91 A resource container. Every valid sliver belongs to exactly one slice. The `toplevelauthority` must match that of the slice authority.
     92`sliver`
     93 A collection of resources which has been instantiated within a slice at a single aggregate. The `toplevelauthority` must match that of the aggregate manager; the corresponding slice is not identified in the sliver URN.
     94`user`
     95 A GENI end user. Users are associated with slice authorities, but not unique slices; the slice to user correspondence is potentially many-to-many. The `toplevelauthority` must match that of the issuing authority.
     96
     97Additional types may be defined in the future.
    6098
    6199''Note: For ProtoGENI compatibility, slice credentials should be signed by an authority with name "sa", e.g., urn:publicid:IDN+gcf:gpo+authority+sa.''
    62100
    63101=== Name ===
    64 The <name> string can be any valid string constrained by the URN character set (e.g. no whitespace).
     102The <name> string can in general be any valid string constrained by the URN character set (e.g. no whitespace).
    65103
     104However, names for certain URN types are restricted:
    66105
     106'''Slice''':
     107 - Slice URN alone is a label - unique at a point in time but not over time.
     108 - Format: `urn:publicid:IDN+<SA name>+slice+<slice name>`
     109 - Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): `'^[a-zA-Z0-9][-a-zA-Z0-9]+$'`
    67110
     111'''Sliver''':
     112 - URN should be unique over time within an AM for record-keeping / operations purposes.
     113 - Format: `urn:publicid:IDN+<AM name>+sliver+<sliver name>`
     114 - Sliver names
     115  - Must be unique over time within that AM, and are selected by the AM.
     116  - May use only alphanumeric characters plus hyphen.
     117
     118'''User''':
     119 - Usernames are case-insensitive internally, though they may be case-sensitive in display.
     120  - EG !JohnSmth as a display name is johnsmth internally, and there cannot also be a user `JOHNSMTH`.
     121 - Usernames should begin with a letter and be alphanumeric or underscores - no hyphen or '.': `('^[a-zA-Z][\w]+$')`.
     122 - Usernames are limited to 8 characters.
     123 - User URNs (which contain the authority name and the username) are required to be temporally and globally unique.
    68124
    69125{{{