Version 13 (modified by 12 years ago) (diff) | ,
---|
GENI Credentials
Credentials are used to authorize actions (where certificates authenticate and URNs identify). They specify the permissions of the Owner relative to a Target object.
In the AM API, credentials have a type and version string. This page documents credentials of type geni_sfa
and version 3.
A 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 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.
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'.
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 of when the credential becomes invalid. If no timezone is specified, times are assumed to be in UTC. 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
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 thetoplevelauthority
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.
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 (1)
-
credential.xsd (10.4 KB) - added by 11 years ago.
GENI credential schema v2
Download all attachments as: .zip