Version 3 (modified by Aaron Helsinger, 10 years ago) (diff)


GENI API: Certificates

Certificates are used to Authenticate actors in the GENI APIs.

The GENI Aggregate Manager API uses X509 certificates to bind public keys to identifiers (URNs). Only the holder of the private key that signed 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.


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

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

        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,
            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/
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
            RSA Public Key: (1024 bit)
                Modulus (1024 bit):
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Subject Key Identifier: 
            X509v3 Subject Alternative Name: 
      ,, URI:urn:uuid:433b6339-43f0-4d88-b5f8-5709de6dff3b
    Signature Algorithm: md5WithRSAEncryption

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

openssl x509 -in mycert.pem -text


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

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:

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