<commit_before>CAPortal 
====================================

A portal interface to an OpenCA DB that provides: 
- Host and client certificate request and renewal with CSR creation using either:
  -> ForgeJS - JavaScript that creates CSR on client or 
  -> BouncyCastle - CSR creation runs on server and is sent back down to client
- .p12 certificate creation using ForgeJS  
- RA certificate management interface: approving/delete/revoke CSR/CRR requests. 
- RA operator list/details.
- TODO: Does not yet provide an interface for CA Operators for managing RA operators,  
  RA details, exporting/signing requests, promoting certs to RA operator, managing 
  bulk requests.    


Note on ForgeJS
----------------
http://digitalbazaar.com/forge/
https://github.com/digitalbazaar/forge 
If you are just interested in creating CSRs using the ForgeJS library, then 
take a look at the following html files that show examples of how to use 
ForgeJS without running the portal: 'src\test\resources\forgeJStests\*.html'. 
These html files can be simply opened in your browser from disk. 
In a number of cases, you will need to use the browser's JavaScript console/debugger
(e.g. Firebug or Chrome console) to view the output.   


Pre-requisites 
---------------
- Servlet container supporting Servlet/JSP spec 2.5/2.1 (e.g. Tomcat v6 or v7). 
- Minimum JavaSE version 1.6 
- This portal uses a legacy OpenCA DB that has some extensions for processing a 
  'bulk' of many certificates. The CA db needs to be deployed and available (Postgres). 
  A 'create_openca_ddl.sql' script is provided to create the DB from scratch. 
  Note, if creating an empty DB, you will probably need to seed the DB with RA details. 
- maven (install maven and configure maven with your http proxy settings, if any) 
  see: http://maven.apache.org/guides/mini/guide-proxies.html 

Configuration 
-------------
- Copy 'WEB-INF/project.propertiesTEMPLATE' to 'WEB-INF/project.properties' and update  
  'WEB-INF/project.properties' to specify your details. This file defines DB 
  connection details and a path to the mutableproperties.properties file. 
- Copy 'WEB-INF/mutableproperties.propertiesTEMPLATE' to 'WEB-INF/mutableproperties.properties' and update  
  to specify your details.
- Configure your servlet container/server for client certificate authentication. This will vary 
  according to your server and can be quite complex (but is just a one time setup). 
  See below for info on how to configure Tomcat. 
- Specify your preferred logging level in 'src/main/resources/log4j.xml'
- Build


Building
---------
Run the following maven targets to clean/build/package. Note, if this is the
first time you have run mvn, it will need to download/install various
maven plugins and dependencies into your local maven repo (~/.m2) and so may take some time: 

- 'mvn clean'
- 'mvn compile'  
- 'mvn package' (note, the war file is built in 'target/caportal-<versionSNAPSHOT>.war
                Rename this file to 'caportal.war' and deploy to your Servlet container). 

Deploy
-------
- Deploy 'target/caportal.war' to your servlet container. This normally requires 
  copying the war file to the servers 'webapps' directory. 
- MUST see Note below on BouncyCastle provided jar files. 


Note on BouncyCastle Provided Jar files
----------------------------------------
The 'pom.xml' file defines two BouncyCastle <dependency> elements for the following 
jar files: 'bcprov-jdk15on.jar' and 'bcpkix-jdk15on.jar'. 
After building, these jar files will be downloaded and will be available in your 
local maven repo (e.g. '$HOME/.m2/repository/org/bouncycastle/'). 

For deployment, you can either:   
- a) package these jars with your application when building, in which case 
  remove the '<scope>provided</scope>' for each these jar's <dependency> elements
  in 'pom.xml', then re-build OR 
- b) manually copy these jars into the server's shared/common lib directory, in which case 
  do specify the '<scope>provided</scope>' in pom.xml so that these jars are NOT 
  packaged into the final .war file (i.e. they are provided by the server). 

It is strongly recommended to go with option b) i.e. manually copy these jars in the server's 
common/shared lib. This means other webapps will be able to use them; 
Since these are special security provider jars, the class loader only allows
them to be loaded once by the first webapp that uses them. Therefore if 
you have another webapp that uses BC, they will not be able to load these jars. 
For Apache Tomcat, the shared/common lib dir is '<TOMCAT_HOME>/lib' 





Configuring Tomcat for client cert auth
========================================
Overview
--------
Basically, you need to configure the Tomcat <Connector> (in server.xml) for SSL by specifying 
both a server certificate and trust (CA) certificates. Importantly, config of this element varies depending on  
whether you choose to use the Tomcat APR (apache portable runtime) Connector or the 
Tomcat JSSE Connector (the <Connector> supports different attributes depending on this choice
as shown below!). 

- See: http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html
- See: http://tomcat.apache.org/tomcat-6.0-doc/connectors.html
- See JSSE Connector: http://tomcat.apache.org/tomcat-6.0-doc/config/http.html#SSL%20Support
- See APR Connector: http://tomcat.apache.org/tomcat-6.0-doc/apr.html


JSSE Connector SSL and Client Cert authentication
------------------------------------------------
- See JSSE Connector: http://tomcat.apache.org/tomcat-6.0-doc/config/http.html#SSL%20Support

The validity of the client cert needs to be verified against the cert authority which 
created it. Therefore, we need Tomcat to trust the client's cert issuer. In 
production, we would want to have the UK eScience certs only (ukescienceRoot and 2B certs) while
for the Dev CA we require the Dev CA cert only. To do this, 
export the issuer cert from a .p12 and import into a separate trust store file: 

```
$ keytool -exportcert -alias DevelopmentCA -keystore someKeystore.p12 -storetype PKCS12 -file DevelopmentCA.pem 
$ keytool -importcert -alias DevelopmentCA -keystore tomcatTrustStoreDevCA.jks -file DevelopmentCA.pem
```
You can then list the trust store using: 
```
$keytool -list -keystore tomcatTrustStoreDevCa.jks
 Enter keystore password:
 Keystore type: JKS
 Keystore provider: SUN
 Your keystore contains 1 entry
 developmentca, 05-Dec-2012, trustedCertEntry,
 Certificate fingerprint (MD5): B8:8F:67:4A:19:10:82:66:99:CB:93:57:9D:59:EA:B9
```

This new trust store file can then be used to configure the JSSE connector's truststoreFile 
setting, e.g: 

```xml
 <Connector 
   protocol="org.apache.coyote.http11.Http11Protocol"
   SSLEnabled="true" 
   clientAuth="want" 
   keystoreFile="C:/Program Files (x86)/Apache Software Foundation/apache-tomcat-6.0.35/conf/djm76DellHostCert.p12" 
   keystorePass="<PASSWORD>" 
   keystoreType="PKCS12" 
   maxThreads="150" 
   port="8443" 
   scheme="https" 
   secure="true" 
   <!-- sslProtocol="TLS"--> 
   sslProtocols = "TLSv1,TLSv1.1,TLSv1.2"        <!-- Tomcat 5 and 6 (prior to 6.0.38) -->
   sslEnabledProtocols = "TLSv1,TLSv1.1,TLSv1.2" <!-- Tomcat 6 (6.0.38 and later) and 7 -->
   truststoreFile="C:/Program Files (x86)/Apache Software Foundation/apache-tomcat-6.0.35/conf/tomcatTrustStoreDevCA.jks" 
   truststorePass="<PASSWORD>" 
   truststoreType="JKS"/>
``` 

  See: https://access.redhat.com/solutions/1232233
  If the sslEnabledProtocols or sslProtocols attributes are specified, only protocols that are listed and supported 
  by the SSL implementation will be enabled. If not specified, the JVM default is used. The permitted values may be 
  obtained from the JVM documentation for the allowed values for algorithm when creating an SSLContext instance e.g.
  Oracle Java 6 and Oracle Java 7.
 
 APR Connector SSL and Client Cert authentication
--------------------------------------------------
- See APR Connector: http://tomcat.apache.org/tomcat-6.0-doc/apr.html
- See: https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/ 

```xml
 <Connector
        protocol="org.apache.coyote.http11.Http11AprProtocol"
        port="8443"
        maxThreads="200"
        scheme="https"
        secure="true"
        SSLEnabled="true"
        SSLVerifyClient="optional"
        SSLCertificateFile="/etc/grid-security/hostcert.pem"
        SSLCertificateKeyFile="/etc/grid-security/hostkey.pem"
        SSLCertificateChainFile="/etc/grid-security/TerenaTrustChain.pem"
        SSLCACertificateFile="/etc/grid-security/e-ScienceTrustChain.pem"
        SSLCipherSuite="ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS"
        SSLProtocol="TLSv1" />
```
- See: https://access.redhat.com/solutions/1232233
  The default is for the SSLProtocol attribute to be set to ALL, with other acceptable values being SSLv2, SSLv3, TLSv1 and SSLv2+SSLv3. 
  Starting with version 1.1.21 of the Tomcat native library any combination of the three protocols concatenated with a plus sign will be supported

Notes
------
- By default, if the tomcat installation is native APR, then it will use the openssl 
implementation, otherwise it will use the Java JSSE implementation. To avoid auto 
configuration you can define which implementation to use by specifying a classname in 
the 'protocol' attribute of the Connector.  <commit_msg>updating doc for apache reverse proxy setup, no logic change<commit_after>CAPortal 
====================================

A portal interface to an OpenCA DB that provides: 
- Host and client certificate request and renewal with CSR creation using either:
  -> ForgeJS - JavaScript that creates CSR on client or 
  -> BouncyCastle - CSR creation runs on server and is sent back down to client
- .p12 certificate creation using ForgeJS  
- RA certificate management interface: approving/delete/revoke CSR/CRR requests. 
- RA operator list/details.
- TODO: Does not yet provide an interface for CA Operators for managing RA operators,  
  RA details, exporting/signing requests, promoting certs to RA operator, managing 
  bulk requests.    


Note on ForgeJS
----------------
http://digitalbazaar.com/forge/
https://github.com/digitalbazaar/forge 
If you are just interested in creating CSRs using the ForgeJS library, then 
take a look at the following html files that show examples of how to use 
ForgeJS without running the portal: 'src\test\resources\forgeJStests\*.html'. 
These html files can be simply opened in your browser from disk. 
In a number of cases, you will need to use the browser's JavaScript console/debugger
(e.g. Firebug or Chrome console) to view the output.   


Pre-requisites 
---------------
- Servlet container supporting Servlet/JSP spec 2.5/2.1 (e.g. Tomcat v6 or v7). 
- Minimum JavaSE version 1.6 
- This portal uses a legacy OpenCA DB that has some extensions for processing a 
  'bulk' of many certificates. The CA db needs to be deployed and available (Postgres). 
  A 'create_openca_ddl.sql' script is provided to create the DB from scratch. 
  Note, if creating an empty DB, you will probably need to seed the DB with RA details. 
- maven (install maven and configure maven with your http proxy settings, if any) 
  see: http://maven.apache.org/guides/mini/guide-proxies.html 

Configuration 
-------------
- Copy 'WEB-INF/project.propertiesTEMPLATE' to 'WEB-INF/project.properties' and update  
  'WEB-INF/project.properties' to specify your details. This file defines DB 
  connection details and a path to the mutableproperties.properties file. 
- Copy 'WEB-INF/mutableproperties.propertiesTEMPLATE' to 'WEB-INF/mutableproperties.properties' and update  
  to specify your details.
- Configure your WebServer and servlet container/server for client certificate authentication. This will vary 
  according to your server and can be quite complex (but is just a one time setup). 
  See below for info on how to configure Apache and Tomcat. 
- Specify your preferred logging level in 'src/main/resources/log4j.xml'
- Build


Building
---------
Run the following maven targets to clean/build/package. Note, if this is the
first time you have run mvn, it will need to download/install various
maven plugins and dependencies into your local maven repo (~/.m2) and so may take some time: 

- 'mvn clean'
- 'mvn compile'  
- 'mvn package' (note, the war file is built in 'target/caportal-<versionSNAPSHOT>.war
                Rename this file to 'caportal.war' and deploy to your Servlet container). 

Deploy
-------
- Deploy 'target/caportal.war' to your servlet container. This normally requires 
  copying the war file to the servers 'webapps' directory. 
- MUST see Note below on BouncyCastle provided jar files. 


Note on BouncyCastle Provided Jar files
----------------------------------------
The 'pom.xml' file defines two BouncyCastle <dependency> elements for the following 
jar files: 'bcprov-jdk15on.jar' and 'bcpkix-jdk15on.jar'. 
After building, these jar files will be downloaded and will be available in your 
local maven repo (e.g. '$HOME/.m2/repository/org/bouncycastle/'). 

For deployment, you can either:   
- a) package these jars with your application when building, in which case 
  remove the '<scope>provided</scope>' for each these jar's <dependency> elements
  in 'pom.xml', then re-build OR 
- b) manually copy these jars into the server's shared/common lib directory, in which case 
  do specify the '<scope>provided</scope>' in pom.xml so that these jars are NOT 
  packaged into the final .war file (i.e. they are provided by the server). 

It is strongly recommended to go with option b) i.e. manually copy these jars in the server's 
common/shared lib. This means other webapps will be able to use them; 
Since these are special security provider jars, the class loader only allows
them to be loaded once by the first webapp that uses them. Therefore if 
you have another webapp that uses BC, they will not be able to load these jars. 
For Apache Tomcat, the shared/common lib dir is '<TOMCAT_HOME>/lib' 





Configuring Front end WebServer  for Client Cert Auth
========================================
Basically, you can either configure Tomcat as the front-end webserver (not recommended) or run Tomcat behind Apache HTTPD
as a reverse proxy and let Apache perform the client certificate prompting/validation (strongly recommended). Both options are 
detailed below. 

##Use Apache HTTPD as front-end WebServer and configure Apache for SSL
This is the recommended approach because apache is more configurable for SSL and client cert authentication. In your apache config, use mod_proxy to pass/reverse-pass requests to/from the tomcat instance via Tomcat's ajp connector. You will also need to use <Location> directives to specify the URLs that require client certificate verification. 
Your apache installation will require configuring with the CA certificates for your CA and the host cert/key.

Sample apache config fragment (not all shown): 
```
#   SSL Engine Switch:
#   Enable/Disable SSL for this virtual host.
SSLEngine on

# Use mod_proxy to pass all requests to/from the target Tomcat's ajp connector
ProxyPass         /  ajp://localhost:8009/
ProxyPassReverse  /  ajp://localhost:8009/

# Specify which webapp URLs need client certificate verification
# (note we also specify the urls with trailing forward slash so that all 
# child-urls also require client-cert auth, e.g. /caporta/cert_owner/) 
 
# URLs for Cert owner pages
<Location /caportal/cert_owner>
  SSLVerifyClient require
  SSLVerifyDepth 10
</Location>
<Location /caportal/cert_owner/>
  SSLVerifyClient require
  SSLVerifyDepth 10
</Location>

# URLs for RA ops pages
<Location /caportal/raop>
  SSLVerifyClient require
  SSLVerifyDepth 10
</Location>
<Location /caportal/raop/>
  SSLVerifyClient require
  SSLVerifyDepth 10
</Location>

# URLs for CA operator pages
<Location /caportal/caop>
  SSLVerifyClient require
  SSLVerifyDepth 10
</Location>
<Location /caportal/caop/>
  SSLVerifyClient require
  SSLVerifyDepth 10
</Location>

# this option is mandatory to force apache to forward the client cert data to tomcat
SSLOptions +ExportCertData

#   SSL Protocol support:
# List the enable protocol levels with which clients will be able to
# connect.  Disable SSLv2 access by default:
SSLProtocol all -SSLv2 -SSLv3
SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH

# Specify host cert/key/CA certs etc 
SSLCertificateFile /etc/grid-security/portal.ca.grid-support.ac.uk.crt
SSLCertificateKeyFile /etc/grid-security/portal.ca.grid-support.ac.uk.key
SSLCertificateChainFile /etc/grid-security/quovadis-chain.crt
SSLCACertificatePath /etc/grid-security/certificates/
SSLCARevocationPath  /etc/grid-security/certificates/
```

Sample tomcat server.xml fragment (not all shown):
```
<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
```

##Use Tomcat as front-end WebServer and configure Tomcat for SSL
Not recommended. Basically, you need to configure the Tomcat <Connector> (in server.xml) for SSL by specifying 
both a server certificate and trust (CA) certificates. Importantly, config of this element varies depending on  
whether you choose to use the Tomcat APR (apache portable runtime) Connector or the 
Tomcat JSSE Connector (the <Connector> supports different attributes depending on this choice
as shown below!). 

- See: http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html
- See: http://tomcat.apache.org/tomcat-6.0-doc/connectors.html
- See JSSE Connector: http://tomcat.apache.org/tomcat-6.0-doc/config/http.html#SSL%20Support
- See APR Connector: http://tomcat.apache.org/tomcat-6.0-doc/apr.html


###JSSE Connector SSL and Client Cert authentication
- See JSSE Connector: http://tomcat.apache.org/tomcat-6.0-doc/config/http.html#SSL%20Support

The validity of the client cert needs to be verified against the cert authority which 
created it. Therefore, we need Tomcat to trust the client's cert issuer. In 
production, we would want to have the UK eScience certs only (ukescienceRoot and 2B certs) while
for the Dev CA we require the Dev CA cert only. To do this, 
export the issuer cert from a .p12 and import into a separate trust store file: 

```
$ keytool -exportcert -alias DevelopmentCA -keystore someKeystore.p12 -storetype PKCS12 -file DevelopmentCA.pem 
$ keytool -importcert -alias DevelopmentCA -keystore tomcatTrustStoreDevCA.jks -file DevelopmentCA.pem
```
You can then list the trust store using: 
```
$keytool -list -keystore tomcatTrustStoreDevCa.jks
 Enter keystore password:
 Keystore type: JKS
 Keystore provider: SUN
 Your keystore contains 1 entry
 developmentca, 05-Dec-2012, trustedCertEntry,
 Certificate fingerprint (MD5): B8:8F:67:4A:19:10:82:66:99:CB:93:57:9D:59:EA:B9
```

This new trust store file can then be used to configure the JSSE connector's truststoreFile 
setting, e.g: 

```xml
 <Connector 
   protocol="org.apache.coyote.http11.Http11Protocol"
   SSLEnabled="true" 
   clientAuth="want" 
   keystoreFile="C:/Program Files (x86)/Apache Software Foundation/apache-tomcat-6.0.35/conf/djm76DellHostCert.p12" 
   keystorePass="<PASSWORD>" 
   keystoreType="PKCS12" 
   maxThreads="150" 
   port="8443" 
   scheme="https" 
   secure="true" 
   <!-- sslProtocol="TLS"--> 
   sslProtocols = "TLSv1,TLSv1.1,TLSv1.2"        <!-- Tomcat 5 and 6 (prior to 6.0.38) -->
   sslEnabledProtocols = "TLSv1,TLSv1.1,TLSv1.2" <!-- Tomcat 6 (6.0.38 and later) and 7 -->
   truststoreFile="C:/Program Files (x86)/Apache Software Foundation/apache-tomcat-6.0.35/conf/tomcatTrustStoreDevCA.jks" 
   truststorePass="<PASSWORD>" 
   truststoreType="JKS"/>
``` 

  See: https://access.redhat.com/solutions/1232233
  If the sslEnabledProtocols or sslProtocols attributes are specified, only protocols that are listed and supported 
  by the SSL implementation will be enabled. If not specified, the JVM default is used. The permitted values may be 
  obtained from the JVM documentation for the allowed values for algorithm when creating an SSLContext instance e.g.
  Oracle Java 6 and Oracle Java 7.
 
### APR Connector SSL and Client Cert authentication
- See APR Connector: http://tomcat.apache.org/tomcat-6.0-doc/apr.html
- See: https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/ 

```xml
 <Connector
        protocol="org.apache.coyote.http11.Http11AprProtocol"
        port="8443"
        maxThreads="200"
        scheme="https"
        secure="true"
        SSLEnabled="true"
        SSLVerifyClient="optional"
        SSLCertificateFile="/etc/grid-security/hostcert.pem"
        SSLCertificateKeyFile="/etc/grid-security/hostkey.pem"
        SSLCertificateChainFile="/etc/grid-security/TerenaTrustChain.pem"
        SSLCACertificateFile="/etc/grid-security/e-ScienceTrustChain.pem"
        SSLCipherSuite="ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS"
        SSLProtocol="TLSv1" />
```
- See: https://access.redhat.com/solutions/1232233
  The default is for the SSLProtocol attribute to be set to ALL, with other acceptable values being SSLv2, SSLv3, TLSv1 and SSLv2+SSLv3. 
  Starting with version 1.1.21 of the Tomcat native library any combination of the three protocols concatenated with a plus sign will be supported

###Notes
- By default, if the tomcat installation is native APR, then it will use the openssl 
implementation, otherwise it will use the Java JSSE implementation. To avoid auto 
configuration you can define which implementation to use by specifying a classname in 
the 'protocol' attribute of the Connector.  
{'fraction_non_alphanumeric': 0.0993286121585579, 'fraction_numerical': 0.017888347282258805, 'mean_word_length': 3.800662251655629, 'pattern_counts': {'":': 0, '<': 52, '<?xml version=': 0, '>': 56, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 15}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '271164', 'n_tokens_mistral': 6816, 'n_tokens_neox': 6279, 'n_words': 2466}