Changes between Initial Version and Version 1 of GeniApiCertificates

Timestamp:

08/13/10 19:09:24 (14 years ago)

Author:

tmitchel@bbn.com

Comment:

--

GeniApiCertificates

@@ +1 @@
+[[PageOutline]]
+
+= GENI API: Certificates =
+
+Certificates are used to Authenticate actors in the GENI API. 
+
+The 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.
+
+In the GENI API, 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 API uses the certificates as part of [wiki:GAPI_Credentials] to authorize the client to execute actions on the server.
+
+=== Format ===
+A 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:
+
+{{{
+Certificate:
+    Data:
+        Version: 1 (0x0)
+        Serial Number: 3 (0x3)
+        Signature Algorithm: md5WithRSAEncryption
+        Issuer: CN=plc.gpo.site2
+        Validity
+            Not Before: Jun 10 17:15:29 2010 GMT
+            Not After : Jun  9 17:15:29 2015 GMT
+        Subject: CN=plc.gpo.site2.jkarlin
+        Subject Public Key Info:
+            Public Key Algorithm: rsaEncryption
+            RSA Public Key: (2048 bit)
+                Modulus (2048 bit):
+                    00:bd:94:7a:7c:b7:76:c9:58:24:15:5d:e9:bf:06:
+                    12:63:d4:f2:47:c3:a0:4b:f0:06:eb:da:19:d6:7d:
+                    81:07:d5:7f:64:ad:a3:aa:32:ce:32:6d:ed:54:ca:
+                    a9:8e:61:9a:49:e8:db:a7:29:ff:7e:23:73:a5:fe:
+                    45:79:f4:e7:1b:5f:34:7c:43:89:a1:a8:76:41:0e:
+                    5a:66:e7:8f:28:9c:19:c0:54:21:fb:49:ca:60:d9:
+                    20:f0:c9:85:58:d3:93:30:5f:36:bb:c9:3e:44:ee:
+                    f0:3e:0f:4a:68:d2:77:33:48:2a:08:a7:e9:7c:41:
+                    21:5a:68:26:9c:f0:b6:3a:76:42:78:d9:dd:32:92:
+                    80:6c:4c:8c:fa:b9:45:38:2c:71:99:57:69:39:a3:
+                    75:3d:65:b7:02:64:cf:3d:9c:1c:90:b6:fe:3b:38:
+                    26:73:51:b7:6c:f7:0a:44:84:9c:35:58:88:78:3c:
+                    f8:47:19:65:df:b6:4d:dc:69:07:09:d1:14:19:08:
+                    14:a6:07:6e:19:de:5d:91:38:3b:7b:b8:4c:c9:a9:
+                    e9:b1:d7:8c:80:b6:87:95:7c:28:3e:28:b9:73:43:
+                    41:5c:55:ee:d0:d2:52:e1:cf:f3:f5:3e:7c:12:f7:
+                    0e:20:ee:26:4a:28:e3:b5:8b:e3:84:7c:d4:4e:e4:
+                    9a:31
+                Exponent: 35 (0x23)
+        X509v3 extensions:
+            X509v3 Basic Constraints: critical
+                CA:TRUE
+            X509v3 Subject Alternative Name: 
+                URI:urn:publicid:IDN+plc:gpo:site2+user+jkarlin
+    Signature Algorithm: md5WithRSAEncryption
+        82:39:3f:b2:1b:85:7c:18:32:13:ea:6d:32:47:e6:a4:df:5d:
+        4e:48:7e:95:96:41:3e:b7:71:9a:f9:9c:5b:7a:f1:34:04:ca:
+        c7:21:26:31:4c:77:8c:b6:57:6e:02:32:8c:84:9f:cf:4b:3e:
+        65:d4:97:76:56:fd:5c:05:5d:02:63:ca:e2:48:dd:54:07:60:
+        35:8a:04:6c:52:5e:a5:ea:f9:66:16:54:e8:7c:32:89:a7:e8:
+        46:5e:af:ea:3b:d6:29:0f:45:e3:80:46:53:d8:e2:bd:9a:68:
+        2a:9e:52:72:6a:3b:2c:40:8a:79:6a:1f:df:34:ed:20:cc:c8:
+        7f:2b
+}}}
+
+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
+aXRlMjAeFw0xMDA2MTAxNzE1MjlaFw0xNTA2MDkxNzE1MjlaMCAxHjAcBgNVBAMT
+FXBsYy5ncG8uc2l0ZTIuamthcmxpbjCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
+AQgCggEBAL2Ueny3dslYJBVd6b8GEmPU8kfDoEvwBuvaGdZ9gQfVf2Sto6oyzjJt
+7VTKqY5hmkno26cp/34jc6X+RXn05xtfNHxDiaGodkEOWmbnjyicGcBUIftJymDZ
+IPDJhVjTkzBfNrvJPkTu8D4PSmjSdzNIKgin6XxBIVpoJpzwtjp2QnjZ3TKSgGxM
+jPq5RTgscZlXaTmjdT1ltwJkzz2cHJC2/js4JnNRt2z3CkSEnDVYiHg8+EcZZd+2
+TdxpBwnRFBkIFKYHbhneXZE4O3u4TMmp6bHXjIC2h5V8KD4ouXNDQVxV7tDSUuHP
+8/U+fBL3DiDuJkoo47WL44R81E7kmjECASOjejB4MA8GA1UdEwEB/wQFMAMBAf8w
+ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK3VzZXIr
+amthcmxpboYtdXJuOnV1aWQ6MDllM2I1ZTEtNzdjMy00OTRkLTk0YWYtZWQ3YjRj
+YWY2YmJkMA0GCSqGSIb3DQEBBAUAA4GBAII5P7IbhXwYMhPqbTJH5qTfXU5IfpWW
+QT63cZr5nFt68TQEyschJjFMd4y2V24CMoyEn89LPmXUl3ZW/VwFXQJjyuJI3VQH
+YDWKBGxSXqXq+WYWVOh8Momn6EZer+o71ikPReOARlPY4r2aaCqeUnJqOyxAinlq
+H9807SDMyH8r
+-----END CERTIFICATE-----
+}}}
+
+
+=== 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 the above certificate, the following lines declare that the subject is an intermediate CA:
+{{{
+            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
+aXRlMjAeFw0xMDA2MTAxNzE1MjlaFw0xNTA2MDkxNzE1MjlaMCAxHjAcBgNVBAMT
+FXBsYy5ncG8uc2l0ZTIuamthcmxpbjCCASAwDQYJKoZIhvcNAQEBBQADggENADCC
+AQgCggEBAL2Ueny3dslYJBVd6b8GEmPU8kfDoEvwBuvaGdZ9gQfVf2Sto6oyzjJt
+7VTKqY5hmkno26cp/34jc6X+RXn05xtfNHxDiaGodkEOWmbnjyicGcBUIftJymDZ
+IPDJhVjTkzBfNrvJPkTu8D4PSmjSdzNIKgin6XxBIVpoJpzwtjp2QnjZ3TKSgGxM
+jPq5RTgscZlXaTmjdT1ltwJkzz2cHJC2/js4JnNRt2z3CkSEnDVYiHg8+EcZZd+2
+TdxpBwnRFBkIFKYHbhneXZE4O3u4TMmp6bHXjIC2h5V8KD4ouXNDQVxV7tDSUuHP
+8/U+fBL3DiDuJkoo47WL44R81E7kmjECASOjejB4MA8GA1UdEwEB/wQFMAMBAf8w
+ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK3VzZXIr
+amthcmxpboYtdXJuOnV1aWQ6MDllM2I1ZTEtNzdjMy00OTRkLTk0YWYtZWQ3YjRj
+YWY2YmJkMA0GCSqGSIb3DQEBBAUAA4GBAII5P7IbhXwYMhPqbTJH5qTfXU5IfpWW
+QT63cZr5nFt68TQEyschJjFMd4y2V24CMoyEn89LPmXUl3ZW/VwFXQJjyuJI3VQH
+YDWKBGxSXqXq+WYWVOh8Momn6EZer+o71ikPReOARlPY4r2aaCqeUnJqOyxAinlq
+H9807SDMyH8r
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIICFTCCAX4CAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
+Fw0xMDA2MTAxNzE1MjhaFw0xNTA2MDkxNzE1MjhaMBgxFjAUBgNVBAMTDXBsYy5n
+cG8uc2l0ZTIwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKfMXAqlXrR3+EfW
+UOY2SCjbSd11+oKbj8RUkp3Axjnm02Wo5pOTrLSaFhORARcmtvsxyfNn6rEYBCJ0
+T+oNAC5HwSRFBpWKiRtW43+iRO9RQaxFo6rsBem65AuZZC3V2jXMvPmI9DCmcibF
+1v4rN3kTGw6WnC3joswqPnFcgolBAgMBAAGjejB4MA8GA1UdEwEB/wQFMAMBAf8w
+ZQYDVR0RBF4wXIYrdXJuOnB1YmxpY2lkOklETitwbGM6Z3BvOnNpdGUyK2F1dGhv
+cml0eStzYYYtdXJuOnV1aWQ6M2I1YjMyNjctY2MzZC00MmE1LTg3ZmEtYjJjMTY5
+ODgyOWIzMA0GCSqGSIb3DQEBBAUAA4GBAGVnGyuPaQdvqr5sydIdxVcbG9Vo+RoN
+weTaG8eU7oQNjeBp4IwgJkC++EKYudCcG6JIl2LiensB6mTYmkvf8GPIbTKDwCdj
+UWKOoez+EiWNZl7PQDgq/wXKn54VctMuyJesFYaVoztIy8ngYIQRJPqsHQdE1suC
+zgNeDVgGkGsz
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIB+DCCAWECAQMwDQYJKoZIhvcNAQEEBQAwEjEQMA4GA1UEAxMHcGxjLmdwbzAe
+Fw0xMDA2MTAxNzE1MjhaFw0xNTA2MDkxNzE1MjhaMBIxEDAOBgNVBAMTB3BsYy5n
+cG8wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJtvhZx43pjyYronJHqdoqxq
+7ir8nxOtOHxWKnTLYCPGSK2W1AxUljeTbTu0QI22kzlqNnVHw6iigTS1jr9uVr0Z
+ic5CtNPajt4kpcF6dFfIo7D+V10XJqy6uU++kkZ5qFt503KBMELm2pSiedrwIvxh
+MEdErlAL99fAfsAGIMFZAgMBAAGjYzBhMF8GA1UdEQRYMFaGJXVybjpwdWJsaWNp
+ZDpJRE4rcGxjOmdwbythdXRob3JpdHkrc2GGLXVybjp1dWlkOjNjY2NkNWM4LTEw
+ODItNDU5OS04MTY4LTU1YTA5NjA3MjM4OTANBgkqhkiG9w0BAQQFAAOBgQBkufkv
+HW3EooAEBz5LWnCCEZf0qR6o9cR9r8ZnkczoShgEPdEfnYBtQGE5a3kt5RXJvPKJ
+iGsg/eWBYpUfsEcwFDYzIxoHNH/rmxgwy6mItIQ90dQNdVYLvXEhtrya+3dkVhPa
+qhhEfubmtMeptqr40vuXaioWnBlY3CDRO88sew==
+-----END CERTIFICATE-----
+
+}}}
+
+{{{
+#!comment
+
+THE HIERARCHY STUFF IS NO LONGER IN THE API
+
+
+== X509 ==
+X509 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).
+
+ * Note: the following fields are not yet finalized!
+ * The issuer field should be the issuer's URN.
+ * The CN of an xmlrpc server should be its domain name so that the client can verify the server.
+ * The CN of any other object should be the URN of the subject.
+ * The email should be the subject's URN.
+
+
+== CA Hierarchy ==
+
+SFA 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.
+
+CAs 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.  
+
+Each 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.
+
+== Obtaining User Certificates ==
+
+Currently, user certificates are obtained out of band.
+
+== Example Certificate ==
+
+[attachment:foobar_cert_chain.pem]
+
+This 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.  
+
+== OpenSSL Primer ==
+
+As 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.
+
+==== Creating a Root CA ====
+
+In a new directory, run 
+{{{
+./CA.sh -newca
+}}}
+
+You probably want the common name to match your server's dns name so that client's can verify who they are speaking with.
+
+==== Creating a Certificate ====
+
+From the Root CA's directory, run
+{{{
+./CA.sh -newreq  # fill out values
+./CA.sh -sign       # sign with the root CA's key
+}}}
+
+You now have newcert.pem and newkey.pem which belong to the user or object.
+
+==== Creating a new Intermediate CA ====
+
+From the ROOT CA's directory, run
+{{{
+./CA.sh -newreq   # fill out values
+./CA.sh -subsign  # just like creating a certificate, but adds an option for CA privileges
+}}}
+
+Now make a new directory for your Intermediate CA (ICA)
+
+Copy the newcert.pem and newkey.pem to your ICA directory
+
+Change to the ICA directory
+
+{{{
+./CA.sh -newca   # pass it your newcert.pem (even though it doesn't appear to work correctly
+cp newcert.pem demoCA/cacert.pem
+cp newkey.pem demoCA/private/cakey.pem
+}}}
+
+
+Now you can create certificates from your intermediate CA
+
+==== Creating a new Certificate from the ICA, and creating a chain file for it ====
+
+{{{
+./CA.sh -newreq
+./CA.sh -sign
+cp newcert.pem newchain.pem
+cat demoCA/cacert.pem >> newchain.pem
+cat $ROOTCA/cacert.pem >> newchain.pem  # replace $ROOTCA with your root CA's directory
+}}}
+
+And now you can distribute the newchain.pem and newkey.pem to the user or object.
+}}}
+
+{{{
+#!comment
+=== FIXME ===
+ - how does this relate to SFA? PG? PL? 
+ - 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?
+ - Ditto for the Subject CN? And how does the Subject CN string relate to the URN in the Subject Alt Name?
+ - What are the naming rules for relating issuer CN to Subject CN? IE must one be derived from the other?
+ - clarify that the example chained cert is showing a user, a CH, and a CA in that order, all in PEM format
+}}}