Project: Bouncy Castle (Provisioning / Security & Compliance)
File: README.md

The examples below use utility scripts, these scripts will try to ensure the dependencies are met to run the examples. To do this ahead of time run the following: ``` cd <bc-java>/test/est/example ./ensurejar.sh ``` This script will download the provider from the betas page and it will then endeavour to build, using gradle the Bouncycastle distribution. You will need to have installed gradle and have it on the PATH for this to run. When it is done building it will then copy the jars into the ```<bc-java>/test/est/example/jars/``` directory. If you need to refresh these jars delete the jars directory or use ```./ensurejar.sh force``` The Cisco EST server will reject TLS version 1 'TLSv1' handshakes. This is the default in Java 7, however Java 8 defaults to TLSv1.2 which the Cisco test EST server will accept. When using Java 7 you will need to supply the argument: ```--tls TLSv1.2``` The examples need a provider, the pkix jar, and the test jar. If you have openjdk installed you can simply use gradle to compile bc-java and the libraries will be in ``` cd <bc-java> gradle -x test clean jar ``` NB: The above was built disabling the tests. OpenJDK does not enforce provider signing which can be advantageous in testing. If you are using a JVM that does enforce provider signing then you will need to download the provider from the betas page. If you are familiar with .BAT files you will be able to examine each .sh file to see how to invoke the examples. The code can be found in ``` /src/main/java/org/bouncycastle/test/est/examples ``` The utility scripts to run each example can be found in same folder as this file. The Bouncycastle EST client makes no assumptions about trust anchors, it assumes that the caller either can supply trust anchors or it cannot, if you don't supply trust anchors the only interaction you may perform is to request CA certificates from an EST server using the Bootstrapping procedure defined in RFC 7030. ``` -t <file> Trust anchor file. (PEM) -u <url> Server Hostname --printTLS <url> Print TLS certificates as PEM format --tls <version> Use this TLS version when creating socket factory, Eg TLSv1.2 --tlsProvider <provider> <class> The JSSE Provider. --to <milliseconds> Timeout in milliseconds. --no-name-verifier No hostname verifier. --label <ca label> CA

``` If bootstrapping is used, the user will be asked to manually validate the certificates, you will be presented with the peer certificates from the TLS connection first, then you will be presented with the CA certificate second. You will need to confirm by typing 'y [enter]' for each certificate: ``` ./cacerts.sh -u testrfc7030.com:8443 Subject: CN=testrfc7030.cisco.com, O="Cisco Systems, Inc.", L=San Jose, ST=CA, C=US Issuer: CN=HydrantID SSL ICA G2, O=HydrantID (Avalanche Cloud Corporation), C=US Serial Number: 14501330919915432666369885490604141760160130548 Not Before: Tue Oct 11 01:02:35 AEDT 2016 Not After: Thu Oct 11 01:02:29 AEDT 2018 Signature Algorithm: SHA256withRSA Subject: CN=HydrantID SSL ICA G2, O=HydrantID (Avalanche Cloud Corporation), C=US Issuer: CN=QuoVadis Root CA 2, O=QuoVadis Limited, C=BM Serial Number: 668466794465057825139349354921536757627739689900 Not Before: Wed Dec 18 01:25:10 AEDT 2013 Not After: Mon Dec 18 01:25:10 AEDT 2023 Signature Algorithm: SHA256withRSA As part of the TLS handshake, the server tendered to us these certificates. Do you accept these certificates (y,n) ? y The untrusted server tendered to us these certificates as CA certs Subject: CN=estExampleCA Issuer: CN=estExampleCA Serial Number: 13965287907438568554 Not Before: Thu Sep 08 03:19:39 AEST 2016 Not After: Fri Sep 08 03:19:39 AEST 2017 Signature Algorithm: org.bouncycastle.asn1.x509.AlgorithmIdentifier@ca7a8819 Do you accept these certificates (y,n) ? y Fetched CA Certs: --BEGIN CERTIFICATE-- MIIBUjCB+aADAgECAgkAwc6rXEzvJGowCQYHKoZIzj0EATAXMRUwEwYDVQQDEwxl c3RFeGFtcGxlQ0EwHhcNMTYwOTA3MTcxOTM5WhcNMTcwOTA3MTcxOTM5WjAXMRUw EwYDVQQDEwxlc3RFeGFtcGxlQ0EwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQs JmLuU8faAKwGQs6A0WpYlwdwR/C0U6kvIIMjcLdPX+OBtYtHo2B8WMDOU5AkGgZ+ Bmy9ZdaZj2BTqGqsiNSioy8wLTAMBgNVHRMEBTADAQH/MB0GA1UdDgQWBBTSse7P EyPT3DkGbsMutPbRjWpKdDAJBgcqhkjOPQQBA0kAMEYCIQDtdmXQD7TQo/mLMsce Hw+Xzwb+1WhQoG8ra1PkEugcygIhAPOZ/L5cnpw/1S8rpVfxSVXUOQpatrgIo50y WmAvxibh --END CERTIFICATE-- ``` As we are using the Cisco Test Server: ``` http://testrfc7030.com/ ``` In order to proceed you will need copy the last TLS certificate and use that as a trust anchor for the remaining examples: ``` ./cacerts.sh -u testrfc7030.com:8443 --printTLS ``` Answer the prompts as usual and at the very the TLS peer certificates will be printed PEM encoded. Take the last one of those and use it as a trust anchor, so cut and paste that into a file. Or try this one, but be aware it may not be current. Copy the certificate to the file: ```server.ta.pem``` ``` --BEGIN CERTIFICATE-- MIIGxDCCBKygAwIBAgIUdRcWd4PQQ361VsNXlG5FY7jr06wwDQYJKoZIhvcNAQEL BQAwRTELMAkGA1UEBhMCQk0xGTAXBgNVBAoTEFF1b1ZhZGlzIExpbWl0ZWQxGzAZ BgNVBAMTElF1b1ZhZGlzIFJvb3QgQ0EgMjAeFw0xMzEyMTcxNDI1MTBaFw0yMzEy MTcxNDI1MTBaMF4xCzAJBgNVBAYTAlVTMTAwLgYDVQQKEydIeWRyYW50SUQgKEF2 YWxhbmNoZSBDbG91ZCBDb3Jwb3JhdGlvbikxHTAbBgNVBAMTFEh5ZHJhbnRJRCBT U0wgSUNBIEcyMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA9p1ZOA9+ H+tgdln+STF7bdOxvnOERYyjo8ZbKumzigNePSwbQYVWuso76GI843yjaX2rhn0+ Jt0NVJM41jVctf9qwacVduR7CEi0qJgpAUJyZUuB9IpFWF1Kz14O3Leh6URuRZ43 RzHaRmNtzkxttGBuOtAg+ilOuwiGAo9VQLgdONlqQFcrbp97/fO8ZIqiPrbhLxCZ fXkYi3mktZVRFKXG62FHAuH1sLDXCKba3avDcUR7ykG4ZXcmp6kl14UKa8JHOHPE NYyr0R6oHELOGZMox1nQcFwuYMX9sJdAUU/9SQVXyA6u6YtxlpZiC8qhXM1IE00T Q9+q5ppffSUDMC4V/5If5A6snKVP78M8qd/RMVswcjMUMEnov+wykwCbDLD+IReM A57XX+HojN+8XFTL9Jwge3z3ZlMwL7E54W3cI7f6cxO5DVwoKxkdk2jRIg37oqSl SU3z/bA9UXjHcTl/6BoLho2p9rWm6oljANPeQuLHyGJ3hc19N8nDo2IATp70klGP kd1qhIgrdkki7gBpanMOK98hKMpdQgs+NY4DkaMJqfrHzWR/CYkdyUCivFaepaFS K78+jVu1oCMOFOnucPXL2fQa3VQn+69+7mA324frjwZj9NzrHjd0a5UP7waPpd9W 2jZoj4b+g+l+XU1SQ+9DWiuZtvfDW++k0BMCAwEAAaOCAZEwggGNMBIGA1UdEwEB /wQIMAYBAf8CAQAweAYDVR0gBHEwbzAIBgZngQwBAgEwCAYGZ4EMAQICMA4GDCsG AQQBvlgAAmQBAjBJBgwrBgEEAb5YAAOHBAAwOTA3BggrBgEFBQcCARYraHR0cDov L3d3dy5oeWRyYW50aWQuY29tL3N1cHBvcnQvcmVwb3NpdG9yeTByBggrBgEFBQcB AQRmMGQwKgYIKwYBBQUHMAGGHmh0dHA6Ly9vY3NwLnF1b3ZhZGlzZ2xvYmFsLmNv bTA2BggrBgEFBQcwAoYqaHR0cDovL3RydXN0LnF1b3ZhZGlzZ2xvYmFsLmNvbS9x dnJjYTIuY3J0MA4GA1UdDwEB/wQEAwIBBjAfBgNVHSMEGDAWgBQahGK8SEwzJQTU 7tD2A8QZRtGUazA5BgNVHR8EMjAwMC6gLKAqhihodHRwOi8vY3JsLnF1b3ZhZGlz Z2xvYmFsLmNvbS9xdnJjYTIuY3JsMB0GA1UdDgQWBBSYarYtLr+nqp/299YJr9WL V/mKtzANBgkqhkiG9w0BAQsFAAOCAgEAlraik8EDDUkpAnIOajO9/r4dpj/Zry76 6SH1oYPo7eTGzpDanPMeGMuSmwdjUkFUPALuWwkaDERfz9xdyFL3N8CRg9mQhdtT 3aWQUv/iyXULXT87EgL3b8zzf8fhTS7r654m9WM2W7pFqfimx9qAlFe9XcVlZrUu 9hph+/MfWMrUju+VPL5U7hZvUpg66mS3BaN15rsXv2+Vw6kQsQC/82iJLHvtYVL/ LwbNio18CsinDeyRE0J9wlYDqzcg5rhD0rtX4JEmBzq8yBRvHIB/023o/vIO5oxh 83Hic/2Xgwksf1DKS3/z5nTzhsUIpCpwkN6nHp6gmA8JBXoUlKQz4eYHJCq/ZyC+ BuY2vHpNx6101J5dmy7ps7J7d6mZXzguP3DQN84hjtfwJPqdf+/9RgLriXeFTqwe snxbk2FsPhwxhiNOH98GSZVvG02v10uHLVaf9B+puYpoUiEqgm1WG5mWW1PxHstu Ew9jBMcJ6wjQc8He9rSUmrhBr0HyhckdC99RgEvpcZpV2XL4nPPrTI2ki/c9xQb9 kmhVGonSXy5aP+hDC+Ht+bxmc4wN5x+vB02hak8Hh8jIUStRxOsRfJozU0R9ysyP EZAHFZ3Zivg2BaD4tOISO8/T2FDjG7PNUv0tgPAOKw2t94B+1evrSUhqJDU0Wf9c 9vkaKoPvX4w= --END CERTIFICATE-- ``` If you have a trust anchor then fetching CA certs will simply return the CA cert, if the server cannot be validated with the trust anchor it will fail. ``` ./cacerts.sh -u testrfc7030.com:8443 -t

Fetched CA Certs: --BEGIN CERTIFICATE-- MIIBUjCB+aADAgECAgkAwc6rXEzvJGowCQYHKoZIzj0EATAXMRUwEwYDVQQDEwxl c3RFeGFtcGxlQ0EwHhcNMTYwOTA3MTcxOTM5WhcNMTcwOTA3MTcxOTM5WjAXMRUw EwYDVQQDEwxlc3RFeGFtcGxlQ0EwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAAQs JmLuU8faAKwGQs6A0WpYlwdwR/C0U6kvIIMjcLdPX+OBtYtHo2B8WMDOU5AkGgZ+ Bmy9ZdaZj2BTqGqsiNSioy8wLTAMBgNVHRMEBTADAQH/MB0GA1UdDgQWBBTSse7P EyPT3DkGbsMutPbRjWpKdDAJBgcqhkjOPQQBA0kAMEYCIQDtdmXQD7TQo/mLMsce Hw+Xzwb+1WhQoG8ra1PkEugcygIhAPOZ/L5cnpw/1S8rpVfxSVXUOQpatrgIo50y WmAvxibh --END CERTIFICATE-- ``` _ Unit Tests for CA cert fetching can be found in: ```<bc-java>/test/src/test/java/org/bouncycastle/test/est/TestCACertsFetch.java``` _ To perform enrollment the user must have a trust anchor to verify the EST server, the enrollment example can accept an optional keystore without a trust anchor for client side authentication. The enroll example has a number of options: ``` ./enroll.sh --r Re-enroll -t <file> Trust anchor file -u <url> EST hostname url. -c <common name> EST CN. --keyStore <file> Optional Key Store. --keyStorePass <password> Optional Key Store password. --keyStoreType <JKS> Optional Key Store type, defaults to JKS --auth <realm:user:password> Auth credentials, if real is not --tls <version> Use this TLS version when creating socket factory, Eg TLSv1.2 --tlsProvider <provider> <class> The JSSE Provider. --pop Turn on PoP --to <milliseconds> Timeout in milliseconds. --no-name-verifier No hostname verifier. --label <ca label> CA Label. --save <path to file> Save generated public and private key to file, (PEM) --load <path to file> Load generated public and private key from a file, (PEM) ``` This following enrollment example will generate CSR internally but you an specify the common name, when enrollment is complete it will return a summary of the returned certificate. ``` ./enroll.sh -t server.ta.pem -u testrfc7030.com:8443 --auth estuser:estpwd -c BARRY Subject: CN=BARRY Issuer: CN=estExampleCA Serial Number: 8727 Not Before: Tue Feb 07 16:00:25 AEDT 2017 Not After: Wed Feb 07 16:00:25 AEDT 2018 Signature Algorithm: org.bouncycastle.asn1.x509.AlgorithmIdentifier@ca7a8819 ``` The Enrollment client defaults to use BCJSSE for its TLS provider as it supports the extraction of the TLS unique value required for PoP. At the time of writing, extraction of the TLS unique value is not supported by the default JSSE provider. Unit Tests for Enrollment can be found in: ```test/src/test/java/org/bouncycastle/test/est/TestEnroll.java``` And for reenrollment: ```<bc-java>/test/src/test/java/org/bouncycastle/test/est/TestReEnroll.java``` Use the ```--load <file>``` and ```--save <file>``` to load and save the generated keys used with the CSR for enrollment. The EST server may require that CSRs have a certain set of attributes. These attributes can be fetched from the server and you will need a trust anchor for the server to make this call. ``` -t <file> Trust anchor file. (PEM) -u <url> Server Hostname --tls <version> Use this TLS version when creating socket factory, Eg TLSv1.2 --tlsProvider <provider> <class> The JSSE Provider. --to <milliseconds> Timeout in milliseconds. --no-name-verifier No hostname verifier. --label <ca label> CA Label. ``` To fetch the attributes: ``` ./csrattrs.sh -t server.ta.pem -u testrfc7030.com:8443 1.2.840.113549.1.9.1 1.3.132.0.34 2.16.840.1.101.3.4.2.2 1.3.6.1.1.1.1.22 ``` Unit tests for fetching csr attributes can be found in: ```<bc-java>/test/src/test/java/org/bouncycastle/test/est/TestGetCSRAttrs.java```