Changes between Initial Version and Version 1 of GeniApiCertificates


Ignore:
Timestamp:
08/13/10 19:09:24 (11 years ago)
Author:
tmitchel@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GeniApiCertificates

    v1 v1  
     1[[PageOutline]]
     2
     3= GENI API: Certificates =
     4
     5Certificates are used to Authenticate actors in the GENI API.
     6
     7The GENI Aggregate Manager API uses [http://en.wikipedia.org/wiki/X.509 X509 certificates] to bind public keys to identifiers ([wiki:GAPI_Identifiers URNs]).  Only the holder of the private key that signed the certificate can act as the the user named by the URN.
     8
     9In the GENI API, 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 API uses the certificates as part of [wiki:GAPI_Credentials] to authorize the client to execute actions on the server.
     12
     13=== Format ===
     14A GENI certificate is an [http://en.wikipedia.org/wiki/X.509 X509v3 certificate] that specifies a GENI identifier ([wiki:GAPI_Identifiers 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:
     15
     16{{{
     17Certificate:
     18    Data:
     19        Version: 1 (0x0)
     20        Serial Number: 3 (0x3)
     21        Signature Algorithm: md5WithRSAEncryption
     22        Issuer: CN=plc.gpo.site2
     23        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
     27        Subject Public Key Info:
     28            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)
     50        X509v3 extensions:
     51            X509v3 Basic Constraints: critical
     52                CA:TRUE
     53            X509v3 Subject Alternative Name:
     54                URI:urn:publicid:IDN+plc:gpo:site2+user+jkarlin
     55    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
     64}}}
     65
     66The textual representation of the certificate (above) was derived from the PEM formatted certificate (below) by running:
     67{{{
     68openssl x509 -in mycert.pem -text
     69}}}
     70
     71{{{
     72-----BEGIN CERTIFICATE-----
     73MIICpTCCAg4CAQMwDQYJKoZIhvcNAQEEBQAwGDEWMBQGA1UEAxMNcGxjLmdwby5z
     74aXRlMjAeFw0xMDA2MTAxNzE1MjlaFw0xNTA2MDkxNzE1MjlaMCAxHjAcBgNVBAMT
     75FXBsYy5ncG8uc2l0ZTIuamthcmxpbjCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
     76AQgCggEBAL2Ueny3dslYJBVd6b8GEmPU8kfDoEvwBuvaGdZ9gQfVf2Sto6oyzjJt
     777VTKqY5hmkno26cp/34jc6X+RXn05xtfNHxDiaGodkEOWmbnjyicGcBUIftJymDZ
     78IPDJhVjTkzBfNrvJPkTu8D4PSmjSdzNIKgin6XxBIVpoJpzwtjp2QnjZ3TKSgGxM
     79jPq5RTgscZlXaTmjdT1ltwJkzz2cHJC2/js4JnNRt2z3CkSEnDVYiHg8+EcZZd+2
     80TdxpBwnRFBkIFKYHbhneXZE4O3u4TMmp6bHXjIC2h5V8KD4ouXNDQVxV7tDSUuHP
     818/U+fBL3DiDuJkoo47WL44R81E7kmjECASOjejB4MA8GA1UdEwEB/wQFMAMBAf8w
     82ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK3VzZXIr
     83amthcmxpboYtdXJuOnV1aWQ6MDllM2I1ZTEtNzdjMy00OTRkLTk0YWYtZWQ3YjRj
     84YWY2YmJkMA0GCSqGSIb3DQEBBAUAA4GBAII5P7IbhXwYMhPqbTJH5qTfXU5IfpWW
     85QT63cZr5nFt68TQEyschJjFMd4y2V24CMoyEn89LPmXUl3ZW/VwFXQJjyuJI3VQH
     86YDWKBGxSXqXq+WYWVOh8Momn6EZer+o71ikPReOARlPY4r2aaCqeUnJqOyxAinlq
     87H9807SDMyH8r
     88-----END CERTIFICATE-----
     89}}}
     90
     91
     92=== Hierarchy ===
     93
     94CA 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:
     95{{{
     96            X509v3 Basic Constraints: critical
     97                CA:TRUE
     98}}}
     99
     100Since 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:
     101{{{
     102C
     103B
     104A (optional)
     105}}}
     106
     107An 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:
     108
     109{{{
     110jkarlin@rabbit:~/.omni$ cat jkarlin.pem
     111-----BEGIN CERTIFICATE-----
     112MIICpTCCAg4CAQMwDQYJKoZIhvcNAQEEBQAwGDEWMBQGA1UEAxMNcGxjLmdwby5z
     113aXRlMjAeFw0xMDA2MTAxNzE1MjlaFw0xNTA2MDkxNzE1MjlaMCAxHjAcBgNVBAMT
     114FXBsYy5ncG8uc2l0ZTIuamthcmxpbjCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
     115AQgCggEBAL2Ueny3dslYJBVd6b8GEmPU8kfDoEvwBuvaGdZ9gQfVf2Sto6oyzjJt
     1167VTKqY5hmkno26cp/34jc6X+RXn05xtfNHxDiaGodkEOWmbnjyicGcBUIftJymDZ
     117IPDJhVjTkzBfNrvJPkTu8D4PSmjSdzNIKgin6XxBIVpoJpzwtjp2QnjZ3TKSgGxM
     118jPq5RTgscZlXaTmjdT1ltwJkzz2cHJC2/js4JnNRt2z3CkSEnDVYiHg8+EcZZd+2
     119TdxpBwnRFBkIFKYHbhneXZE4O3u4TMmp6bHXjIC2h5V8KD4ouXNDQVxV7tDSUuHP
     1208/U+fBL3DiDuJkoo47WL44R81E7kmjECASOjejB4MA8GA1UdEwEB/wQFMAMBAf8w
     121ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK3VzZXIr
     122amthcmxpboYtdXJuOnV1aWQ6MDllM2I1ZTEtNzdjMy00OTRkLTk0YWYtZWQ3YjRj
     123YWY2YmJkMA0GCSqGSIb3DQEBBAUAA4GBAII5P7IbhXwYMhPqbTJH5qTfXU5IfpWW
     124QT63cZr5nFt68TQEyschJjFMd4y2V24CMoyEn89LPmXUl3ZW/VwFXQJjyuJI3VQH
     125YDWKBGxSXqXq+WYWVOh8Momn6EZer+o71ikPReOARlPY4r2aaCqeUnJqOyxAinlq
     126H9807SDMyH8r
     127-----END CERTIFICATE-----
     128-----BEGIN CERTIFICATE-----
     129MIICFTCCAX4CAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
     130Fw0xMDA2MTAxNzE1MjhaFw0xNTA2MDkxNzE1MjhaMBgxFjAUBgNVBAMTDXBsYy5n
     131cG8uc2l0ZTIwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKfMXAqlXrR3+EfW
     132UOY2SCjbSd11+oKbj8RUkp3Axjnm02Wo5pOTrLSaFhORARcmtvsxyfNn6rEYBCJ0
     133T+oNAC5HwSRFBpWKiRtW43+iRO9RQaxFo6rsBem65AuZZC3V2jXMvPmI9DCmcibF
     1341v4rN3kTGw6WnC3joswqPnFcgolBAgMBAAGjejB4MA8GA1UdEwEB/wQFMAMBAf8w
     135ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK2F1dGhv
     136cml0eStzYYYtdXJuOnV1aWQ6M2I1YjMyNjctY2MzZC00MmE1LTg3ZmEtYjJjMTY5
     137ODgyOWIzMA0GCSqGSIb3DQEBBAUAA4GBAGVnGyuPaQdvqr5sydIdxVcbG9Vo+RoN
     138weTaG8eU7oQNjeBp4IwgJkC++EKYudCcG6JIl2LiensB6mTYmkvf8GPIbTKDwCdj
     139UWKOoez+EiWNZl7PQDgq/wXKn54VctMuyJesFYaVoztIy8ngYIQRJPqsHQdE1suC
     140zgNeDVgGkGsz
     141-----END CERTIFICATE-----
     142-----BEGIN CERTIFICATE-----
     143MIIB+DCCAWECAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
     144Fw0xMDA2MTAxNzE1MjhaFw0xNTA2MDkxNzE1MjhaMBIxEDAOBgNVBAMTB3BsYy5n
     145cG8wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJtvhZx43pjyYronJHqdoqxq
     1467ir8nxOtOHxWKnTLYCPGSK2W1AxUljeTbTu0QI22kzlqNnVHw6iigTS1jr9uVr0Z
     147ic5CtNPajt4kpcF6dFfIo7D+V10XJqy6uU++kkZ5qFt503KBMELm2pSiedrwIvxh
     148MEdErlAL99fAfsAGIMFZAgMBAAGjYzBhMF8GA1UdEQRYMFaGJXVybjpwdWJsaWNp
     149ZDpJRE4rcGxjOmdwbythdXRob3JpdHkrc2GGLXVybjp1dWlkOjNjY2NkNWM4LTEw
     150ODItNDU5OS04MTY4LTU1YTA5NjA3MjM4OTANBgkqhkiG9w0BAQQFAAOBgQBkufkv
     151HW3EooAEBz5LWnCCEZf0qR6o9cR9r8ZnkczoShgEPdEfnYBtQGE5a3kt5RXJvPKJ
     152iGsg/eWBYpUfsEcwFDYzIxoHNH/rmxgwy6mItIQ90dQNdVYLvXEhtrya+3dkVhPa
     153qhhEfubmtMeptqr40vuXaioWnBlY3CDRO88sew==
     154-----END CERTIFICATE-----
     155
     156}}}
     157
     158{{{
     159#!comment
     160
     161THE HIERARCHY STUFF IS NO LONGER IN THE API
     162
     163
     164== X509 ==
     165X509 PEM formatted certificates.  If the certificate was issued by an intermediate (also known as subordinate) CA, then the intermediate certificates must? be appended to the end of the certificate up to the root (in order from leaf to root).  The resulting chain certificate will be used to open SSL connections (see SSL_CTX_use_certificate_chain_file in the OpenSSL library).
     166
     167 * Note: the following fields are not yet finalized!
     168 * The issuer field should be the issuer's URN.
     169 * The CN of an xmlrpc server should be its domain name so that the client can verify the server.
     170 * The CN of any other object should be the URN of the subject.
     171 * The email should be the subject's URN.
     172
     173
     174== CA Hierarchy ==
     175
     176SFA servers act as Certificate Authorities (CAs).  They create and sign certificates for their own objects (such as nodes in their aggregate) and for their users.
     177
     178CAs can form a hierarchy in which a root CA creates new intermediate CAs as children.  The intermediate CAs have certificates signed by the root CA and "CA:TRUE" in the basic constraints section of their certificate.  Intermediate CAs can create new certificates as well as create new intermediate CAs.  As an example, there might be a GENI root, and a GENI.US, GENI.EU, GENI.EU.ES, and GENI.AS set of intermediate CAs. 
     179
     180Each SFA registry is a CA.  Each SFA Aggregate Manager will have a set of CA keys that they use for verification.  To verify a certificate, the certificate must be signed by one of the trusted CAs or one of their children (or children's children etc.).  If the certificate is signed by an intermediate CA that the AM does not have a key for, then it is necessary to verify that the intermediate CA is an offspring of one of the trusted CAs.  This is accomplished by verifying the certificate, then the parent's certificate, all the way up to a trusted CA.  Therefore, certificates from intermediate CAs should always include this chain of intermediate certificates.
     181
     182== Obtaining User Certificates ==
     183
     184Currently, user certificates are obtained out of band.
     185
     186== Example Certificate ==
     187
     188[attachment:foobar_cert_chain.pem]
     189
     190This certificate is a user certificate for urn:publicid:IDN+geni.net:gpo+user+jkarlin.  It is a chain certificate because it also includes the certificate for urn:publicid:IDN+geni.net:gpo+authority+registry and urn:publicid:IDN+geni.net+authority+registry, which is self signed. 
     191
     192== OpenSSL Primer ==
     193
     194As a primer for creating CAs, subordinates, and certificates, we provide the [attachment:CA.sh] script which is slightly modified from the standard script provided with openssl.
     195
     196==== Creating a Root CA ====
     197
     198In a new directory, run
     199{{{
     200./CA.sh -newca
     201}}}
     202
     203You probably want the common name to match your server's dns name so that client's can verify who they are speaking with.
     204
     205==== Creating a Certificate ====
     206
     207From the Root CA's directory, run
     208{{{
     209./CA.sh -newreq  # fill out values
     210./CA.sh -sign       # sign with the root CA's key
     211}}}
     212
     213You now have newcert.pem and newkey.pem which belong to the user or object.
     214
     215==== Creating a new Intermediate CA ====
     216
     217From the ROOT CA's directory, run
     218{{{
     219./CA.sh -newreq   # fill out values
     220./CA.sh -subsign  # just like creating a certificate, but adds an option for CA privileges
     221}}}
     222
     223Now make a new directory for your Intermediate CA (ICA)
     224
     225Copy the newcert.pem and newkey.pem to your ICA directory
     226
     227Change to the ICA directory
     228
     229{{{
     230./CA.sh -newca   # pass it your newcert.pem (even though it doesn't appear to work correctly
     231cp newcert.pem demoCA/cacert.pem
     232cp newkey.pem demoCA/private/cakey.pem
     233}}}
     234
     235
     236Now you can create certificates from your intermediate CA
     237
     238==== Creating a new Certificate from the ICA, and creating a chain file for it ====
     239
     240{{{
     241./CA.sh -newreq
     242./CA.sh -sign
     243cp newcert.pem newchain.pem
     244cat demoCA/cacert.pem >> newchain.pem
     245cat $ROOTCA/cacert.pem >> newchain.pem  # replace $ROOTCA with your root CA's directory
     246}}}
     247
     248And now you can distribute the newchain.pem and newkey.pem to the user or object.
     249}}}
     250
     251{{{
     252#!comment
     253=== FIXME ===
     254 - how does this relate to SFA? PG? PL?
     255 - what are rules/specs on the Issuer CN? That's a CH? A CA? How is the name specified? How does that relate to a URN?
     256 - Ditto for the Subject CN? And how does the Subject CN string relate to the URN in the Subject Alt Name?
     257 - What are the naming rules for relating issuer CN to Subject CN? IE must one be derived from the other?
     258 - clarify that the example chained cert is showing a user, a CH, and a CA in that order, all in PEM format
     259}}}