wiki:GeniApiCertificates

  1. GENI API: Certificates
      1. Format
      2. Validation
      3. Hierarchy

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

GENI API: Certificates

GENI uses X.509 v3 certificates to (1) Authenticate actors in the GENI APIs, (2) protect message transport, specifically the SSL transport layer for APIs such as the AM API, and (3) to formally identify actors as members within GENI credentials.

The GENI Aggregate Manager API uses ​X509 certificates (formally defined ​in RFC5280) to bind public keys to identifiers (URNs). Only the holder of the private key corresponding to the public key contained in the certificate can act as the the user named by the URN. Aggregates are required to properly validate all certificates to authenticate access to AM API calls, and fail calls that supply invalid certificates.

In the GENI APIs, these certificates are used for both server side authentication and client side authentication in SSL connections (actually https).

Once the SSL library has established the secure authenticated communications channel using these certificates, the GENI AM API uses the certificates as part of GeniApiCredentials to authorize the client to execute actions on the server.

Format

A GENI certificate is an ​X509v3 certificate that specifies a GENI identifier (URN) in the X509v3 subjectAltName extension. It is stored in PEM format which is described in the ​X.509 wikipedia page. The GENI identifier (URN) is placed in ​URI format and begins with: 'URI:urn:publicid:IDN+'. The certificate's Common Name (CN) values for the Issuer and Subject are not specified by the GENI specifications and can be any valid common name.

Certificate contents restrictions and requirements:

  • 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.
  • The Subject Alternative Name field must include 3 pieces of information
    • Entries are comma separated (', '), and may be in any order.
    • The URN identifier, following GENI URN standards as described here: 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.
    • 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.
    • 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:stoller@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. Tool certificates shall provide an address to contact the administrators of the tool instance - the organization or individual who applied for the certificate and who stands behind its integrity. These addresses may be aliases.
  • Recommendation: Authorities are encouraged but not required to include a URL where more information about the subject is available (e.g. slice authority registry URL). That URL may be included in a certificate extension, in the DN, or in the subjectAltName.

The following is an example GENI certificate that uses a dotted notation for the common names: 

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 49758 (0xc25e)
        Signature Algorithm: md5WithRSAEncryption
        Issuer: C=US, ST=Utah, L=Salt Lake City, O=Utah Network Testbed, OU=Certificate Authority, CN=boss.emulab.net/emailAddress=testbed-ops@flux.utah.edu
        Validity
            Not Before: Jan 21 20:18:39 2011 GMT
            Not After : Jan 21 20:18:39 2012 GMT
        Subject: C=US, ST=Utah, O=Utah Network Testbed, OU=utahemulab.ahelsing, CN=68a0a4c1-258a-11e0-b35d-001143e453fe/emailAddress=ahelsing@emulab.net
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (1024 bit)
                Modulus (1024 bit):
                    00:b7:42:73:e1:dc:61:16:47:50:cb:44:4e:c1:65:
                    d7:5b:3e:ad:df:a3:0c:14:8b:94:65:62:a1:94:06:
                    ec:e9:2b:9b:27:d8:40:75:f4:fc:51:dc:43:19:71:
                    42:9e:ce:1f:9a:46:02:8d:72:3d:ea:fe:c6:df:02:
                    af:e6:1a:49:e3:8d:95:33:bc:df:ce:ef:7d:19:18:
                    00:be:99:09:6c:5e:61:41:78:5e:83:7c:cd:6d:64:
                    ed:66:da:d5:2c:eb:83:45:38:ce:f6:f7:20:fc:a8:
                    56:46:54:57:4f:0c:50:82:92:ba:0b:1f:2e:a7:ff:
                    9e:cb:02:d6:2c:b0:77:81:c1
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
                A8:85:C1:50:7C:B6:99:CC:34:80:5A:91:1A:1E:C0:35:59:B8:87:3D
            X509v3 Subject Alternative Name: 
                URI:urn:publicid:IDN+emulab.net+user+ahelsing, email:ahelsing@emulab.net, URI:urn:uuid:433b6339-43f0-4d88-b5f8-5709de6dff3b
    Signature Algorithm: md5WithRSAEncryption
        82:54:0d:13:e1:81:22:de:98:2e:e0:c2:3b:a0:43:e9:b6:26:
        2b:3d:73:9a:ca:41:60:ae:8a:5f:44:73:06:6d:80:38:91:0a:
        4e:77:a6:d6:73:33:f7:a8:92:d8:ad:60:47:68:82:e8:52:64:
        cb:da:aa:74:ae:c5:91:fc:9d:c5:af:cb:9d:14:e4:7e:36:da:
        2c:f8:c2:dc:8b:ca:25:10:00:45:ef:c2:06:d5:60:93:da:fc:
        3b:f2:9b:bd:a9:87:87:e1:d2:44:1b:4f:e0:5c:f9:73:16:38:
        4c:16:68:a3:14:73:9c:97:b9:e6:0a:3e:a8:41:8e:ea:d8:4d:
        5b:76

The textual representation of the certificate (above) was derived from the PEM formatted certificate (below) by running: 

openssl x509 -in mycert.pem -text

-----BEGIN CERTIFICATE-----
MIICpTCCAg4CAQMwDQYJKoZIhvcNAQEEBQAwGDEWMBQGA1UEAxMNcGxjLmdwby5z
.....
H9807SDMyH8r
-----END CERTIFICATE-----

Validation

To be valid, certificates must:

  • Follow the format rules above
  • Expire later than the current time
  • Be issued by a trusted certificate (possibly via a certificate chain)
    • Issuer's certificate must also validate
    • Signers must be marked as a CA, per above
    • Signers must have a URN indicating they are of type authority, as described in the URN wiki page
    • Signers must have namespace authority over the subject of the certificate
      • Essentially, the authority name of the signer must be a prefix of the subject name. EG: a\.b is an authority for, a\.b.c.d, but a is not an authority for, a\.b.c.d (the subject's name starts with a.b, where we've escaped the .). Also any authority name is an authority for itself.

For sample python code to validate GENI certificates, 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.

Hierarchy

CA hierarchies are supported. In a CA hierarchy, a root CA can create normal certificates as well as intermediate CA certificates. Intermediate CAs are able to issue certificates that are verified by following the chain from the certificate to the intermediate CA's certificate to the root certificate. Typically, the verifier will only have the root CA's certificate installed for verification, and the intermediate CA's certificates is appended to the certificates it issues (called PEM chaining). In GENI, user and slice authorities are CAs. Certificates for CAs are required to be declared as a CA, and others (users, slices) should NOT be declared as a CA, as in: 

            X509v3 Basic Constraints: critical
                CA:TRUE

Since Aggregates and Control Frameworks are likely to only have the root CA's certificate installed, and not the intermediate CA certs, all certs signed by an intermediate CA should be chained. A chained certificate is simply a certificate that appends the issuer's certificate to the end of the file. For instance, if A is a root CA cert, B is an intermediate CA cert, and C is an end-user certificate, then C's chained certificate is: 

C
B
A (optional)

An example chained certificate which shows the Usert cert, the intermediate CA cert, and the root CA cert (in that order from top to bottom) in chained PEM format: 

jkarlin@rabbit:~/.omni$ cat jkarlin.pem
-----BEGIN CERTIFICATE-----
MIICpTCCAg4CAQMwDQYJKoZIhvcNAQEEBQAwGDEWMBQGA1UEAxMNcGxjLmdwby5z
...
H9807SDMyH8r
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICFTCCAX4CAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
...
zgNeDVgGkGsz
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIB+DCCAWECAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
...
qhhEfubmtMeptqr40vuXaioWnBlY3CDRO88sew==
-----END CERTIFICATE-----
Last modified 8 years ago Last modified on 11/02/16 22:02:05