| | 1 | [[PageOutline]] |
| | 2 | |
| | 3 | = GENI Credentials = |
| | 4 | |
| | 5 | Credentials are used to authorize actions (where certificates authenticate and URNs identify). They specify the permissions of the Owner relative to a Target object. |
| | 6 | |
| | 7 | 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). |
| | 8 | |
| | 9 | 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. |
| | 10 | |
| | 11 | GENI Credentials are signed XML containing: |
| | 12 | - Owner GID, which is a PEM format X509 certificate, containing the owner's URN in the Subject Alt Name field. See GeniApiCertificates. |
| | 13 | - Owner URN to identify the owner (entity whose permissions are being specified). For information on URNs, see GeniApiIdentifiers. |
| | 14 | - Target GID |
| | 15 | - Target URN |
| | 16 | - Expiration date |
| | 17 | - List of privileges (string names) |
| | 18 | - Signature of the issuer of the credential. The issuer should be an authority over the Target's namespace. See GeniApiIdentifiers. |
| | 19 | |
| | 20 | |
| | 21 | == Credential Format == |
| | 22 | |
| | 23 | The schema is available at http://www.protogeni.net/trac/protogeni/attachment/wiki/Authentication/credential.rnc |
| | 24 | |
| | 25 | {{{ |
| | 26 | <?xml version="1.0"?> |
| | 27 | <signed-credential> |
| | 28 | <credential xml:id="ref0"> |
| | 29 | <type>privilege</type> |
| | 30 | <serial>8</serial> |
| | 31 | <owner_gid>certificate here</owner_gid> |
| | 32 | <owner_urn>urn:publicid:IDN+plc:gpo:site2+user+jkarlin</owner_urn> |
| | 33 | <target_gid>certificate here</target_gid> |
| | 34 | <target_urn>urn:publicid:IDN+plc:gpo:site2+user+jkarlin</target_urn> |
| | 35 | <uuid/> |
| | 36 | <expires>2012-07-14T19:52:08</expires> |
| | 37 | <privileges> |
| | 38 | <privilege> |
| | 39 | <name>refresh</name> |
| | 40 | <can_delegate>true</can_delegate> |
| | 41 | </privilege> |
| | 42 | </privileges> |
| | 43 | </credential> |
| | 44 | |
| | 45 | <signatures> |
| | 46 | signature information here |
| | 47 | </signatures> |
| | 48 | </signed-credential> |
| | 49 | |
| | 50 | |
| | 51 | }}} |
| | 52 | |
| | 53 | ''' Type ''' |
| | 54 | Type can be one of 'privilege', 'ticket', and 'capability'. The GENI AM API is only concerned with privilege credentials. |
| | 55 | |
| | 56 | ''' Serial ''' |
| | 57 | This is a value specified by the issuer, and can be any string. |
| | 58 | |
| | 59 | ''' Owner GID ''' |
| | 60 | 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. |
| | 61 | |
| | 62 | ''' Owner URN ''' |
| | 63 | The URN of the owner. |
| | 64 | |
| | 65 | ''' Target GID ''' |
| | 66 | The X509 certificate of the target of the credential. The certificate should be in PEM format, and can be chained. |
| | 67 | |
| | 68 | ''' Target URN ''' |
| | 69 | 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). |
| | 70 | |
| | 71 | ''' UUID ''' |
| | 72 | This is unused. |
| | 73 | |
| | 74 | ''' Expires ''' |
| | 75 | ISO 8601 date and time of when the credential becomes invalid. |
| | 76 | |
| | 77 | ''' Privileges ''' |
| | 78 | The privileges are the rights that are assigned to the owner of the credential on the target resource. The SFA-derived control frameworks use different permission names, but they have similar semantic meaning. 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. |
| | 79 | |
| | 80 | ''' Signatures ''' |
| | 81 | 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 |
| | 82 | |
| | 83 | ''' Parent ''' |
| | 84 | If the credential is a delegated credential then the original credential is placed within its parent tag. |
| | 85 | |
| | 86 | |
| | 87 | |
| | 88 | == Credential Validation == |
| | 89 | |
| | 90 | Please see http://www.protogeni.net/trac/protogeni/wiki/Credentials for credential verification and validation details. |
| | 91 | |
| | 92 | |
| | 93 | |
| | 94 | |
| | 95 | |
| | 96 | == Development Experience == |
| | 97 | XMLSEC: |
| | 98 | |
| | 99 | 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 |
| | 100 | |
| | 101 | On fedora 8, yum install xmlsec1 xmlsec1-openssl-devel xmlsec1-devel |
| | 102 | |
| | 103 | 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. |
| | 104 | |
| | 105 | |
| | 106 | The signature template is the following (replace "ref0" with the xml:id if your XML section that is signed): |
| | 107 | |
| | 108 | {{{ |
| | 109 | <Signature xml:id="Sig_ref0" xmlns="http://www.w3.org/2000/09/xmldsig#"> |
| | 110 | <SignedInfo> |
| | 111 | <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/> |
| | 112 | <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> |
| | 113 | <Reference URI="#ref0"> |
| | 114 | <Transforms> |
| | 115 | <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" /> |
| | 116 | </Transforms> |
| | 117 | <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/> |
| | 118 | <DigestValue></DigestValue> |
| | 119 | </Reference> |
| | 120 | </SignedInfo> |
| | 121 | <SignatureValue /> |
| | 122 | <KeyInfo> |
| | 123 | <X509Data> |
| | 124 | <X509SubjectName/> |
| | 125 | <X509IssuerSerial/> |
| | 126 | <X509Certificate/> |
| | 127 | </X509Data> |
| | 128 | <KeyValue /> |
| | 129 | </KeyInfo> |
| | 130 | </Signature> |
| | 131 | |
| | 132 | }}} |
| | 133 | |
| | 134 | |
| | 135 | This is a command to sign and verify an XML file with a signature appendage |
| | 136 | |
| | 137 | {{{ |
| | 138 | xmlsec1 sign --node-id "Sig_ref1" --privkey-pem ~/.sfi/jkarlin.pkey,~/.sfi/jkarlin.cert template.xml > signed_template.xml |
| | 139 | }}} |
| | 140 | |
| | 141 | {{{ |
| | 142 | xmlsec1 verify --node-id "Sig_ref1" --trusted-pem intermediate_ca_cert --trusted-pem root_ca_cert signed.xml |
| | 143 | }}} |
| | 144 | |
| | 145 | 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. |
