wiki:GeniApiIdentifiers

Version 1 (modified by tmitchel@bbn.com, 9 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/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

Examples and Usage

An example: urn:publicid:IDN+geni:gpo:gcf+user+joe

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

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 be any valid string constrained by the URN character set (e.g. no whitespace).

Attachments (1)

Download all attachments as: .zip