Changes between Version 2 and Version 3 of GeniApiCertificates


Ignore:
Timestamp:
04/19/12 10:09:44 (10 years ago)
Author:
Aaron Helsinger
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GeniApiCertificates

    v2 v3  
    33= GENI API: Certificates =
    44
    5 Certificates are used to Authenticate actors in the GENI API.
    6 
    7 The GENI Aggregate Manager API uses [http://en.wikipedia.org/wiki/X.509 X509 certificates] to bind public keys to identifiers ([wiki:GeniApiIdentifiers URNs]).  Only the holder of the private key that signed the certificate can act as the the user named by the URN.
    8 
    9 In the GENI API, these certificates are used for both server side authentication and client side authentication in SSL connections (actually https).
    10 
    11 Once the SSL library has established the secure authenticated communications channel using these certificates, the GENI API uses the certificates as part of [wiki:GeniApiCredentials] to authorize the client to execute actions on the server.
     5Certificates are used to Authenticate actors in the GENI APIs.
     6
     7The GENI Aggregate Manager API uses [http://en.wikipedia.org/wiki/X.509 X509 certificates] to bind public keys to identifiers ([wiki:GeniApiIdentifiers 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.
     8
     9In the GENI APIs, these certificates are used for both server side authentication and client side authentication in SSL connections (actually https).
     10
     11Once the SSL library has established the secure authenticated communications channel using these certificates, the GENI AM API uses the certificates as part of [wiki:GeniApiCredentials] to authorize the client to execute actions on the server.
    1212
    1313=== Format ===
    14 A GENI certificate is an [http://en.wikipedia.org/wiki/X.509 X509v3 certificate] that specifies a GENI identifier ([wiki:GeniApiIdentifiers URN]) in the X509v3 subjectAltName extension.  It is stored in PEM format which is described in the [http://en.wikipedia.org/wiki/X.509 X.509 wikipedia page]. The GENI identifier (URN) is placed in [http://en.wikipedia.org/wiki/Uniform_Resource_Identifier 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.  The following is an example GENI certificate that uses a dotted notation for the common names:
     14A GENI certificate is an [http://en.wikipedia.org/wiki/X.509 X509v3 certificate] that specifies a GENI identifier ([wiki:GeniApiIdentifiers URN]) in the X509v3 subjectAltName extension.  It is stored in PEM format which is described in the [http://en.wikipedia.org/wiki/X.509 X.509 wikipedia page]. The GENI identifier (URN) is placed in [http://en.wikipedia.org/wiki/Uniform_Resource_Identifier 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. 
     15
     16Certificate contents restrictions and requirements:
     17 - {{{Version}}} shall be properly marked: 3
     18 - {{{serialNum}}} is required to be unique within the certificate authority: each newly issued certificate must have a unique serial number.
     19 - The Distinguished Name should include a human readable identifier, for both subject and issuer. Details are not specified
     20 - 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}}}.
     21 - The Subject Alternative Name field must include 3 pieces of information
     22  - Entries are comma separated ('{{{, }}}'), and may be in any order.
     23  - The URN identifier, following GENI URN standards as described here: GeniApiIdentifiers
     24   - The URN is identifiable by looking for the entry beginning "{{{URI:urn:publicid:IDN}}}", for example: {{{URI:urn:publicid:IDN+emulab.net+user+stoller}}}.
     25  - A UUID, providing a unique ID for the entity.
     26   - 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.
     27   - In the hexadecimal digit string format given in [http://www.ietf.org/rfc/rfc4122.txt RFC 4122]
     28   - The UUID is identified with this prefix: "{{{URI:urn:uuid}}}" (as specified by RFC4122), for example: {{{URI:urn:uuid:33178d77-a930-40b1-9469-3aae08755743}}}.
     29   - The `COPY` tag is not supported.
     30  - The email address is an [http://tools.ietf.org/html/rfc2822#section-3.4.1 RFC2822] compliant and working address for contacting the subject of the certificate (experimenter, authority administrator, or slice owner).
     31   - The email entry is identified by the prefix "{{{email:}}}", for example: {{{email:stoller@example.com}}}
     32   - The `COPY` tag is not supported.
     33   - 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.
     34 - 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.
     35
     36The following is an example GENI certificate that uses a dotted notation for the common names:
    1537
    1638{{{
    1739Certificate:
    1840    Data:
    19         Version: 1 (0x0)
    20         Serial Number: 3 (0x3)
     41        Version: 3 (0x2)
     42        Serial Number: 49758 (0xc25e)
    2143        Signature Algorithm: md5WithRSAEncryption
    22         Issuer: CN=plc.gpo.site2
     44        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
    2345        Validity
    24             Not Before: Jun 10 17:15:29 2010 GMT
    25             Not After : Jun  9 17:15:29 2015 GMT
    26         Subject: CN=plc.gpo.site2.jkarlin
     46            Not Before: Jan 21 20:18:39 2011 GMT
     47            Not After : Jan 21 20:18:39 2012 GMT
     48        Subject: C=US, ST=Utah, O=Utah Network Testbed, OU=utahemulab.ahelsing, CN=68a0a4c1-258a-11e0-b35d-001143e453fe/emailAddress=ahelsing@emulab.net
    2749        Subject Public Key Info:
    2850            Public Key Algorithm: rsaEncryption
    29             RSA Public Key: (2048 bit)
    30                 Modulus (2048 bit):
    31                     00:bd:94:7a:7c:b7:76:c9:58:24:15:5d:e9:bf:06:
    32                     12:63:d4:f2:47:c3:a0:4b:f0:06:eb:da:19:d6:7d:
    33                     81:07:d5:7f:64:ad:a3:aa:32:ce:32:6d:ed:54:ca:
    34                     a9:8e:61:9a:49:e8:db:a7:29:ff:7e:23:73:a5:fe:
    35                     45:79:f4:e7:1b:5f:34:7c:43:89:a1:a8:76:41:0e:
    36                     5a:66:e7:8f:28:9c:19:c0:54:21:fb:49:ca:60:d9:
    37                     20:f0:c9:85:58:d3:93:30:5f:36:bb:c9:3e:44:ee:
    38                     f0:3e:0f:4a:68:d2:77:33:48:2a:08:a7:e9:7c:41:
    39                     21:5a:68:26:9c:f0:b6:3a:76:42:78:d9:dd:32:92:
    40                     80:6c:4c:8c:fa:b9:45:38:2c:71:99:57:69:39:a3:
    41                     75:3d:65:b7:02:64:cf:3d:9c:1c:90:b6:fe:3b:38:
    42                     26:73:51:b7:6c:f7:0a:44:84:9c:35:58:88:78:3c:
    43                     f8:47:19:65:df:b6:4d:dc:69:07:09:d1:14:19:08:
    44                     14:a6:07:6e:19:de:5d:91:38:3b:7b:b8:4c:c9:a9:
    45                     e9:b1:d7:8c:80:b6:87:95:7c:28:3e:28:b9:73:43:
    46                     41:5c:55:ee:d0:d2:52:e1:cf:f3:f5:3e:7c:12:f7:
    47                     0e:20:ee:26:4a:28:e3:b5:8b:e3:84:7c:d4:4e:e4:
    48                     9a:31
    49                 Exponent: 35 (0x23)
     51            RSA Public Key: (1024 bit)
     52                Modulus (1024 bit):
     53                    00:b7:42:73:e1:dc:61:16:47:50:cb:44:4e:c1:65:
     54                    d7:5b:3e:ad:df:a3:0c:14:8b:94:65:62:a1:94:06:
     55                    ec:e9:2b:9b:27:d8:40:75:f4:fc:51:dc:43:19:71:
     56                    42:9e:ce:1f:9a:46:02:8d:72:3d:ea:fe:c6:df:02:
     57                    af:e6:1a:49:e3:8d:95:33:bc:df:ce:ef:7d:19:18:
     58                    00:be:99:09:6c:5e:61:41:78:5e:83:7c:cd:6d:64:
     59                    ed:66:da:d5:2c:eb:83:45:38:ce:f6:f7:20:fc:a8:
     60                    56:46:54:57:4f:0c:50:82:92:ba:0b:1f:2e:a7:ff:
     61                    9e:cb:02:d6:2c:b0:77:81:c1
     62                Exponent: 65537 (0x10001)
    5063        X509v3 extensions:
    51             X509v3 Basic Constraints: critical
    52                 CA:TRUE
     64            X509v3 Subject Key Identifier:
     65                A8:85:C1:50:7C:B6:99:CC:34:80:5A:91:1A:1E:C0:35:59:B8:87:3D
    5366            X509v3 Subject Alternative Name:
    54                 URI:urn:publicid:IDN+plc:gpo:site2+user+jkarlin
     67                URI:urn:publicid:IDN+emulab.net+user+ahelsing, email:ahelsing@emulab.net, URI:urn:uuid:433b6339-43f0-4d88-b5f8-5709de6dff3b
    5568    Signature Algorithm: md5WithRSAEncryption
    56         82:39:3f:b2:1b:85:7c:18:32:13:ea:6d:32:47:e6:a4:df:5d:
    57         4e:48:7e:95:96:41:3e:b7:71:9a:f9:9c:5b:7a:f1:34:04:ca:
    58         c7:21:26:31:4c:77:8c:b6:57:6e:02:32:8c:84:9f:cf:4b:3e:
    59         65:d4:97:76:56:fd:5c:05:5d:02:63:ca:e2:48:dd:54:07:60:
    60         35:8a:04:6c:52:5e:a5:ea:f9:66:16:54:e8:7c:32:89:a7:e8:
    61         46:5e:af:ea:3b:d6:29:0f:45:e3:80:46:53:d8:e2:bd:9a:68:
    62         2a:9e:52:72:6a:3b:2c:40:8a:79:6a:1f:df:34:ed:20:cc:c8:
    63         7f:2b
     69        82:54:0d:13:e1:81:22:de:98:2e:e0:c2:3b:a0:43:e9:b6:26:
     70        2b:3d:73:9a:ca:41:60:ae:8a:5f:44:73:06:6d:80:38:91:0a:
     71        4e:77:a6:d6:73:33:f7:a8:92:d8:ad:60:47:68:82:e8:52:64:
     72        cb:da:aa:74:ae:c5:91:fc:9d:c5:af:cb:9d:14:e4:7e:36:da:
     73        2c:f8:c2:dc:8b:ca:25:10:00:45:ef:c2:06:d5:60:93:da:fc:
     74        3b:f2:9b:bd:a9:87:87:e1:d2:44:1b:4f:e0:5c:f9:73:16:38:
     75        4c:16:68:a3:14:73:9c:97:b9:e6:0a:3e:a8:41:8e:ea:d8:4d:
     76        5b:76
    6477}}}
    6578
     
    7285-----BEGIN CERTIFICATE-----
    7386MIICpTCCAg4CAQMwDQYJKoZIhvcNAQEEBQAwGDEWMBQGA1UEAxMNcGxjLmdwby5z
    74 aXRlMjAeFw0xMDA2MTAxNzE1MjlaFw0xNTA2MDkxNzE1MjlaMCAxHjAcBgNVBAMT
    75 FXBsYy5ncG8uc2l0ZTIuamthcmxpbjCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
    76 AQgCggEBAL2Ueny3dslYJBVd6b8GEmPU8kfDoEvwBuvaGdZ9gQfVf2Sto6oyzjJt
    77 7VTKqY5hmkno26cp/34jc6X+RXn05xtfNHxDiaGodkEOWmbnjyicGcBUIftJymDZ
    78 IPDJhVjTkzBfNrvJPkTu8D4PSmjSdzNIKgin6XxBIVpoJpzwtjp2QnjZ3TKSgGxM
    79 jPq5RTgscZlXaTmjdT1ltwJkzz2cHJC2/js4JnNRt2z3CkSEnDVYiHg8+EcZZd+2
    80 TdxpBwnRFBkIFKYHbhneXZE4O3u4TMmp6bHXjIC2h5V8KD4ouXNDQVxV7tDSUuHP
    81 8/U+fBL3DiDuJkoo47WL44R81E7kmjECASOjejB4MA8GA1UdEwEB/wQFMAMBAf8w
    82 ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK3VzZXIr
    83 amthcmxpboYtdXJuOnV1aWQ6MDllM2I1ZTEtNzdjMy00OTRkLTk0YWYtZWQ3YjRj
    84 YWY2YmJkMA0GCSqGSIb3DQEBBAUAA4GBAII5P7IbhXwYMhPqbTJH5qTfXU5IfpWW
    85 QT63cZr5nFt68TQEyschJjFMd4y2V24CMoyEn89LPmXUl3ZW/VwFXQJjyuJI3VQH
    86 YDWKBGxSXqXq+WYWVOh8Momn6EZer+o71ikPReOARlPY4r2aaCqeUnJqOyxAinlq
     87.....
    8788H9807SDMyH8r
    8889-----END CERTIFICATE-----
     
    9293=== Hierarchy ===
    9394
    94 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 the above certificate, the following lines declare that the subject is an intermediate CA:
     95CA 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:
    9596{{{
    9697            X509v3 Basic Constraints: critical
     
    111112-----BEGIN CERTIFICATE-----
    112113MIICpTCCAg4CAQMwDQYJKoZIhvcNAQEEBQAwGDEWMBQGA1UEAxMNcGxjLmdwby5z
    113 aXRlMjAeFw0xMDA2MTAxNzE1MjlaFw0xNTA2MDkxNzE1MjlaMCAxHjAcBgNVBAMT
    114 FXBsYy5ncG8uc2l0ZTIuamthcmxpbjCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
    115 AQgCggEBAL2Ueny3dslYJBVd6b8GEmPU8kfDoEvwBuvaGdZ9gQfVf2Sto6oyzjJt
    116 7VTKqY5hmkno26cp/34jc6X+RXn05xtfNHxDiaGodkEOWmbnjyicGcBUIftJymDZ
    117 IPDJhVjTkzBfNrvJPkTu8D4PSmjSdzNIKgin6XxBIVpoJpzwtjp2QnjZ3TKSgGxM
    118 jPq5RTgscZlXaTmjdT1ltwJkzz2cHJC2/js4JnNRt2z3CkSEnDVYiHg8+EcZZd+2
    119 TdxpBwnRFBkIFKYHbhneXZE4O3u4TMmp6bHXjIC2h5V8KD4ouXNDQVxV7tDSUuHP
    120 8/U+fBL3DiDuJkoo47WL44R81E7kmjECASOjejB4MA8GA1UdEwEB/wQFMAMBAf8w
    121 ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK3VzZXIr
    122 amthcmxpboYtdXJuOnV1aWQ6MDllM2I1ZTEtNzdjMy00OTRkLTk0YWYtZWQ3YjRj
    123 YWY2YmJkMA0GCSqGSIb3DQEBBAUAA4GBAII5P7IbhXwYMhPqbTJH5qTfXU5IfpWW
    124 QT63cZr5nFt68TQEyschJjFMd4y2V24CMoyEn89LPmXUl3ZW/VwFXQJjyuJI3VQH
    125 YDWKBGxSXqXq+WYWVOh8Momn6EZer+o71ikPReOARlPY4r2aaCqeUnJqOyxAinlq
     114...
    126115H9807SDMyH8r
    127116-----END CERTIFICATE-----
    128117-----BEGIN CERTIFICATE-----
    129118MIICFTCCAX4CAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
    130 Fw0xMDA2MTAxNzE1MjhaFw0xNTA2MDkxNzE1MjhaMBgxFjAUBgNVBAMTDXBsYy5n
    131 cG8uc2l0ZTIwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKfMXAqlXrR3+EfW
    132 UOY2SCjbSd11+oKbj8RUkp3Axjnm02Wo5pOTrLSaFhORARcmtvsxyfNn6rEYBCJ0
    133 T+oNAC5HwSRFBpWKiRtW43+iRO9RQaxFo6rsBem65AuZZC3V2jXMvPmI9DCmcibF
    134 1v4rN3kTGw6WnC3joswqPnFcgolBAgMBAAGjejB4MA8GA1UdEwEB/wQFMAMBAf8w
    135 ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK2F1dGhv
    136 cml0eStzYYYtdXJuOnV1aWQ6M2I1YjMyNjctY2MzZC00MmE1LTg3ZmEtYjJjMTY5
    137 ODgyOWIzMA0GCSqGSIb3DQEBBAUAA4GBAGVnGyuPaQdvqr5sydIdxVcbG9Vo+RoN
    138 weTaG8eU7oQNjeBp4IwgJkC++EKYudCcG6JIl2LiensB6mTYmkvf8GPIbTKDwCdj
    139 UWKOoez+EiWNZl7PQDgq/wXKn54VctMuyJesFYaVoztIy8ngYIQRJPqsHQdE1suC
     119...
    140120zgNeDVgGkGsz
    141121-----END CERTIFICATE-----
    142122-----BEGIN CERTIFICATE-----
    143123MIIB+DCCAWECAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
    144 Fw0xMDA2MTAxNzE1MjhaFw0xNTA2MDkxNzE1MjhaMBIxEDAOBgNVBAMTB3BsYy5n
    145 cG8wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJtvhZx43pjyYronJHqdoqxq
    146 7ir8nxOtOHxWKnTLYCPGSK2W1AxUljeTbTu0QI22kzlqNnVHw6iigTS1jr9uVr0Z
    147 ic5CtNPajt4kpcF6dFfIo7D+V10XJqy6uU++kkZ5qFt503KBMELm2pSiedrwIvxh
    148 MEdErlAL99fAfsAGIMFZAgMBAAGjYzBhMF8GA1UdEQRYMFaGJXVybjpwdWJsaWNp
    149 ZDpJRE4rcGxjOmdwbythdXRob3JpdHkrc2GGLXVybjp1dWlkOjNjY2NkNWM4LTEw
    150 ODItNDU5OS04MTY4LTU1YTA5NjA3MjM4OTANBgkqhkiG9w0BAQQFAAOBgQBkufkv
    151 HW3EooAEBz5LWnCCEZf0qR6o9cR9r8ZnkczoShgEPdEfnYBtQGE5a3kt5RXJvPKJ
    152 iGsg/eWBYpUfsEcwFDYzIxoHNH/rmxgwy6mItIQ90dQNdVYLvXEhtrya+3dkVhPa
     124...
    153125qhhEfubmtMeptqr40vuXaioWnBlY3CDRO88sew==
    154126-----END CERTIFICATE-----