wiki:GeniApiIdentifiers

Version 3 (modified by Aaron Helsinger, 8 years ago) (diff)

--

GENI API Identifiers

GENI identifies objects (be it a researcher, resource, clearinghouse, or aggregate manager) with a Uniform Resource Name (URN). The format of a GENI URN is: urn:publicid:IDN+<authority string>+<type>+<name>. The format is adapted from the ProtoGENI URN format and the GMOC GENI URN proposal. All sections of the URN are mandatory. Note that additional '+' characters are allowed in the <name> section.

Public Identifiers

GENI URNs are in the URN namespace for Public Identifiers. As such, each GENI URN is of the form: urn:publicid:{transcribed-public-identifier}. RFC 3151 describes how public identifiers are transcribed to URNs (which involves collapsing whitespace and replacing certain characters with % encoded values).

The public identifier section of a GENI URN must begin with "IDN ". When transcribed, this means that all GENI URNs begin with "urn:publicid:IDN+".

To transcribe a public ID to a URN use the following rules:

From Transcribe to
leading and trailing whitespace trim
whitespace collapse to a single '+'
'' ':'
'::' ';'
'+' '%2B'
":' '%3A'
'/' '%2F'
';' '%3B'
''' '%27'
'?' '%3F'
'#' '%23'
'%' '%25

Example translations:

Public ID GENI URN
IDN plcprinceton authority sa urn:publicid:IDN+plc:princeton+authority+sa
IDN gcfgpogpolab user joe urn:publicid:IDN+gcf:gpo:gpolab+user+joe
IDN gcfgpogpolab node switch 1 port 2 urn:publicid:IDN+gcf:gpo:gpolab+node+switch+1+port+2

Formally, the URN format follows the following naming convention (in perl regular expression syntax for the encoding string):

“IDN [toplevelauthority][\/\/sub-authority]* resource-type resource-name”

This would lead to the following urn schema in the public id namespace (Using the transformation in RFC 3151 :

“urn:publicid:IDN+toplevelauthority[:sub-authority]*\+resource-type\+resource-name”

Where:

toplevelauthority

is an internationalized domain name (which must match the one in the certificate of the authority which issued the object name)

sub-authority

is an internationalized domain name (which must match the one in the certificate of the authority which issued the object name)

resource-type

is a string describing the type of the named object (the set of strings is described below)

resource-name

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.

Examples and Usage

The following examples are borrowed from the GMOC Proposal:

Resource GENI Identifier
User cviecco at the planetlab namespace urn:publicid:IDN+planet-lab.org+user+cviecco
Planetlab node: pl2.ucs.indiana.edu urn:publicid:IDN+planet-lab.org+node+pl2.ucs.indiana.edu
Interface eth0 in planetlab node pl1.ucs.indiana.edu urn:publicid:IDN+planet-lab.org+interface+pl1.ucs.indiana.edu:eth0

Examples of additional types of objects from the ProtoGENI documentation:

Resource GENI Identifier
Slice mytestslice in the Utah Emulab slice authority urn:publicid:IDN+emulab.net+slice+mytestslice
The Utah Emulab slice authority urn:publicid:IDN+emulab.net+authority+sa
Sliver 123 in the Utah Emulab aggregate manager urn:publicid:IDN+emulab.net+sliver+123

In 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).

Authority String

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).

For 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.

Type

The <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.

authority

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.

interface

A component which is an interface (an endpoint for links). The toplevelauthority must match that of the aggregate manager.

link

A component which is a network link (a connection between two or more interfaces). The toplevelauthority must match that of the aggregate manager.

node

A component which is a node (an abstraction for networkable resources). The toplevelauthority must match that of the aggregate manager.

slice

A resource container. Every valid sliver belongs to exactly one slice. The toplevelauthority must match that of the slice authority.

sliver

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.

user

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.

Additional types may be defined in the future.

Note: For ProtoGENI compatibility, slice credentials should be signed by an authority with name "sa", e.g., urn:publicid:IDN+gcf:gpo+authority+sa.

Name

The <name> string can in general be any valid string constrained by the URN character set (e.g. no whitespace).

However, names for certain URN types are restricted:

Slice:

  • Slice URN alone is a label - unique at a point in time but not over time.
  • Format: urn:publicid:IDN+<SA name>+slice+<slice name>
  • Slice names are <=19 characters, only alphanumeric plus hyphen (no hyphen in first character): '^[a-zA-Z0-9][-a-zA-Z0-9]+$'

Sliver:

  • URN should be unique over time within an AM for record-keeping / operations purposes.
  • Format: urn:publicid:IDN+<AM name>+sliver+<sliver name>
  • Sliver names
    • Must be unique over time within that AM, and are selected by the AM.
    • May use only alphanumeric characters plus hyphen.

User:

  • Usernames are case-insensitive internally, though they may be case-sensitive in display.
    • EG JohnSmth as a display name is johnsmth internally, and there cannot also be a user JOHNSMTH.
  • Usernames should begin with a letter and be alphanumeric or underscores - no hyphen or '.': ('^[a-zA-Z][\w]+$').
  • Usernames are limited to 8 characters.
  • User URNs (which contain the authority name and the username) are required to be temporally and globally unique.

Attachments (1)

Download all attachments as: .zip