This page has moved to  https://github.com/GENI-NSF/geni-docs/blob/master/GeniApiCredentials.adoc


GENI Credentials

Credentials are signed assertions used to authorize actions (where certificates authenticate and URNs identify).

In the AM API, credentials have a type and version string. This page documents the GENI SFA credential format, and specifically credentials of type geni_sfa and version 3. These GENI SFA credentials specify the permissions of the Owner relative to a Target object.

The same basic structure is used to specify GENI ABAC credentials (type geni_abac and version 1), but with some important differences.

A GENI SFA credential provides the credential's owner with permissions on a target object (identified by a URN). For instance, with a 'slice credential,' the user is given rights to allocate and remove resources from a slice. The credential format that the GENI AM API uses is adapted from ProtoGENI's credential format described at:  http://www.protogeni.net/trac/protogeni/wiki/Credentials. The only differences between the two formats is that the GENI credential allows for different privileges (those from other control frameworks such as Planet Lab's SFA). Also note that the value of can_delegate on privileges is an  xsd:boolean, meaning it should be one of 1, 0, true, or false.

In the API, method calls take a list of Credentials. The semantics of that list are not specified. The reference GCF implementation treats each credential as a separate option: if any ONE credential grants the subject ALL required privileges on the specified target, then allow the operation. An alternative implementation could accumulate privileges from each otherwise valid credential to determine total permissions.

GENI Credentials are signed XML documents, following  the W3C XML Digital Signature standard, containing:

  • Owner GID, which is a PEM format X509 certificate, containing the owner's URN in the Subject Alt Name field. See GeniApiCertificates.
  • Owner URN to identify the owner (entity whose permissions are being specified). For information on URNs, see GeniApiIdentifiers.
  • Target GID
  • Target URN
  • Expiration date
  • List of privileges (string names)
  • Signature of the issuer of the credential, per  the W3C XML Digital Signature standard. The issuer should be an authority over the Target's namespace. See GeniApiIdentifiers.

Credential Format

The v2 schema (adding ABAC credential support) is attached to this page. The v1 schema is available at  http://www.protogeni.net/trac/protogeni/attachment/wiki/Authentication/credential.rnc

In the AM API, credentials have a type and version string. This page documents credentials of type geni_sfa and version 3. (Credentials of type geni_abac and version 1 are documented at the ABAC credential page.)

Sample credential:

<?xml version="1.0"?>
<signed-credential>
        <credential xml:id="ref0">
                <type>privilege</type>
                <serial>8</serial>
                <owner_gid>certificate here</owner_gid>
                <owner_urn>urn:publicid:IDN+plc:gpo:site2+user+jkarlin</owner_urn>
                <target_gid>certificate here</target_gid>
                <target_urn>urn:publicid:IDN+plc:gpo:site2+user+jkarlin</target_urn>
                <uuid/>
                <expires>2012-07-14T19:52:08Z</expires>
                <privileges>
                        <privilege>
                                <name>refresh</name>
                                <can_delegate>true</can_delegate>
                        </privilege>
                </privileges>
        </credential>

        <signatures>
                signature information here      
        </signatures>
</signed-credential>


Type Type should be 'privilege' for GENI SFA credentials. (For GENI ABAC credentials, the type is 'abac'.)

Serial This is a value specified by the issuer, and can be any string.

Owner GID The X509 certificate of the owner of the credential (who the credential is being made for). The certificate should be in PEM format, and can be chained.

Owner URN The URN of the owner.

Target GID The X509 certificate of the target of the credential. The certificate should be in PEM format, and can be chained.

Target URN The URN of the target. The signer of the credential should either have the same URN as the target (this is a difference from ProtoGENI) or should be an authority over the target URN's namespace (see identifiers).

UUID This is unused.

Expires ISO 8601 date and time through which the assertions contained in this credential are valid. If no timezone is specified, times are assumed to be in UTC. Note that the overall credential may become invalid before this datetime if any embedded certificate expires (see below). Note: Implementations are preferred to use  RFC3339 compliant strings. The  W3C standard has more details on this field.

Privileges The privileges are the rights that are assigned to the owner of the credential on the target resource. Different slice authorities use different permission names, but they have similar semantic meaning. If and only if a privilege can be delegated, then that means the owner of the credential can delegate that permission to another entity. Currently, the only credentials used in the GENI API are slice credentials and user credentials. Privileges have not yet been agreed upon between the control frameworks. Currently, SFA assigns ['refresh', 'resolve', and 'info'] rights to user credentials. Slice credentials have "slice" rights. ProtoGENI defaults to the "*" privilege which means that the owner has rights to all methods associated with that credential type (user or slice). See  https://www.protogeni.net/trac/protogeni/wiki/ReferenceImplementationPrivileges for more information on ProtoGENI privileges.

can_delegate Privileges can be delegated. Every privilege gets a sub-element can_delegate. The value is an  xsd:boolean, meaning it should be one of 1, 0, true, or false.

Signatures The preceding XML is signed using the XML Signature specification (see  http://www.w3.org/TR/xmldsig-core/). SFA and ProtoGENI use the xmlsec1 binary to sign credentials. For more information on using xmlsec1, please see the bottom of this page. If a credential is delegated, then the owner creating the new (delegated) credential signs the new credential and the original signature and the new signature are placed in the <Signatures> section. For more information on delegation please see:  http://www.protogeni.net/trac/protogeni/wiki/Credentials

Parent If the credential is a delegated credential then the original credential is placed within its parent tag.

Delegation

GENI SFA credentials may be delegated, if the owner (subject) has can_delegate for one or more privileges. To generate a delegated credential, the owner re-signs their own credential, granting a subset of their own rights to a new owner. The delegated credential should be for the same target, for the same or a shorter duration, include the original credential in the parent field, be signed by the original credential's subject (subject of parent == issuer of delegated credential), and grant a subset of the original credential's privileges.

Credential Validation

Please see  http://www.protogeni.net/trac/protogeni/wiki/Credentials for a discussion of credential verification and validation details.

To validate a credential:

  • Credentials must validate against the credential schema.
  • The credential signature must be valid, as per the  XML Digital Signature standard.
  • All contained certificates must be valid and trusted (trace back through all valid/trusted certificates to a trusted root certificate), and follow the GENI Certificate restrictions (see GeniApiCertificates).
  • The expiration of the credential and all contained certificates must be later than the current time.
  • All contained URNs must follow the GENI URN rules.
  • The same rules apply to any parent credential, if the credential is delegated (and on up the delegation chain).
  • For non delegated credentials, or for the root credential of a delegated credential (all the way back up any delegation chain), the signer must have authority over the target. Specifically, the credential issuer must have a URN indicating it is of type authority, and it must be the toplevelauthority or a parent authority of the authority named in the credential's target URN. See the URN rules page for details about authorities.
  • For delegated credentials, the signer of the credential must be the subject (owner) of the parent credential), until you get to the root credential (no parent), in which case the above rule applies.

Format Change History

AM API v3 standardized some additional elements of credentials and certificates. The new requirements with AM API v3 are documented on this page, and known as "geni_sfa v3". This section defines the changes from the old format, now known as geni_sfa version 2.

Note: AM API v3 added requirements on URNs and certificates, as well as credentials. A credential is only geni_sfa version 3 if all contained certificates and URNs are AM API v3 compliant. Experimenters with existing certificates that are not AM API v3 compliant will only get geni_sfa version 2 credentials, unless they first get a new user certificate. As a result, most aggregates should accept both geni_sfa version 3 and version 2 credentials.

The full set of changes proposed and accepted is documented here:  http://groups.geni.net/geni/wiki/GAPI_AM_API_V3_DELTAS#Adopted:ChangeSetK:Standardizecertificatesandcredentials

In summary, these changes standardize elements of certificates (used in credentials), and the structure of URNs (including user and slice URNs, used in credentials).

Certificate changes for geni_sfa v3 credentials:

  • The Subject Alternative Name field must include 3 pieces of information: URN, UUID, and Email.
    • v2 credentials could legally includes all 3 of these, but were not required to do so.
    • Entries are comma separated (', '), and may be in any order.
    • 1: The URN identifier, following GENI URN standards as described here:  http://groups.geni.net/geni/wiki/GeniApiIdentifiers
      • The URN is identifiable by looking for the entry beginning "URI:urn:publicid:IDN", for example: URI:urn:publicid:IDN+emulab.net+user+stoller.
    • 2: A UUID, providing a unique ID for the entity.
      • The UUID must be used with the URN to fully identify the slice or user. UUID alone should not be accepted. This ensures that the authority certifying the slice or user is always identified when referring to the slice or user.
      • In the hexadecimal digit string format given in  RFC 4122
      • The UUID is identified with this prefix: "URI:urn:uuid" (as specified by RFC4122), for example: URI:urn:uuid:33178d77-a930-40b1-9469-3aae08755743.
      • The COPY tag is not supported.
    • 3: The email address is an  RFC2822 compliant and working address for contacting the subject of the certificate (experimenter, authority administrator, or slice owner).
      • The email entry is identified by the prefix "email:", for example: email:smith@example.com
      • The COPY tag is not supported.
      • Note that the slice and user email addresses are addresses for contacting the responsible party - the slice owner or creator and the user. These may be aliases.

Certificate elements standardized (but not necessarily changed) for geni_sfa version 3 credentials:

  • Version shall be properly marked: 3
  • serialNum is required to be unique within the certificate authority: each newly issued certificate must have a unique serial number.
  • The Distinguished Name should include a human readable identifier, for both subject and issuer. Details are not specified.
  • Only authority certificates (but all authorities that issue certificates) shall be marked CA:TRUE in the x509 v3 basic constraints; Slices and users shall be marked FALSE.
  • Recommendation: Authorities are encouraged but not required to include a URL where more information about the subject is available (eg slice authority registry URL). That URL may be included in a certificate extension, in the DN, or in the subjectAltName.

Slice URNs are now standardized (not a change):

  • Slice URN 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]\{0,18\}$'
  • Aggregates are required to accept any compliant slice name and URN.

User URNs are now standardized (not a change):

  • User URNs (which contain the authority name and the username) are required to be temporally and globally unique.
  • 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 are limited to 8 characters.
  • Usernames should begin with a letter and be alphanumeric or underscores - no hyphen or '.': ('^[a-zA-Z][\w]\{1,8\}$').

Development Experience

For sample python code to validate GENI credentials, see  http://git.planet-lab.org/?p=sfa.git;a=tree;f=sfa/trust;hb=HEAD, or the  GCF package, under gcf/src/sfa/trust.

 XMLSEC is the standard library for for signing, encrypting, and validating XML digital signatures. For Java libraries, see the  Apache Santuario library.

The xmlsec1 binary (installed as part of the xmlsec library) will take an XML file that has a signature template appended to it and an xml:id attribute, and sign the portion of the XML document designated by the same xml:id using the provided key. The signature is placed within the appended signature template. Discussion of installation and usage is provided below

On fedora 8, yum install xmlsec1 xmlsec1-openssl-devel xmlsec1-devel

If you get errors about unimplemented features when you run 'xmlsec1 --encrypt blah' instead of errors about unable to find file blah, then you need to install more libraries until it's happy.

The signature template is the following (replace "ref0" with the xml:id if your XML section that is signed):

<Signature xml:id="Sig_ref0" xmlns="http://www.w3.org/2000/09/xmldsig#">                                                        
    <SignedInfo>                                                                                                              
      <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>                                   
      <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>                                               
      <Reference URI="#ref0">                                                                                                   
      <Transforms>                                                                                                            
        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />                                       
      </Transforms>                                                                                                           
      <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>                                                      
      <DigestValue></DigestValue>                                                                                             
      </Reference>                                                                                                            
    </SignedInfo>                                                                                                             
    <SignatureValue />                                                                                                        
      <KeyInfo>                                                                                                               
        <X509Data>                                                                                                            
          <X509SubjectName/>                                                                                                  
          <X509IssuerSerial/>                                                                                                 
          <X509Certificate/>                                                                                                  
        </X509Data>                                                                                                           
      <KeyValue />                                                                                                            
      </KeyInfo>                                                                                                              
    </Signature>    

This is a command to sign and verify an XML file with a signature appendage

xmlsec1 sign --node-id "Sig_ref1" --privkey-pem ~/.sfi/jkarlin.pkey,~/.sfi/jkarlin.cert template.xml > signed_template.xml
xmlsec1 verify --node-id "Sig_ref1" --trusted-pem intermediate_ca_cert --trusted-pem root_ca_cert signed.xml

It seems that you can't chain the certificates passed to trusted-pem, it chokes on it. Instead you have to list each cert individually.

Attachments