imported>Mike.berman: 1 revision: Certificate update instructions

2016-08-10T18:16:53Z

1 revision: Certificate update instructions

← Older revision	Revision as of 18:16, 10 August 2016
(No difference)

imported>Cmace: /* Configuring AppBoard for SSL */

2016-08-10T16:58:27Z

Configuring AppBoard for SSL

← Older revision		Revision as of 16:58, 10 August 2016
Line 70:		Line 70:

	See the [[appboard/2.6/admin/runtime_options\|Runtime Options]] page for complete information on all runtime options.		See the [[appboard/2.6/admin/runtime_options\|Runtime Options]] page for complete information on all runtime options.

			=== Replacing Certificates ===

			Once a certificate expires, you will need to generate a new certificate and replace the old one in the keystore. The following steps assume that you are updating the keystore located in <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt>:

			# In the terminal, navigate to your <tt>[JAVA_HOME]/bin/</tt> directory containing the keytool.
			# If you are unsure which certificate you need to replace, you can view the contents of the keystore with:
			#:<tt>keytool -list -v -keystore [INSTALL_HOME]/server/conf/ssl.crt/keystore.jks</tt>
			# Delete the old certificate:
			#: <tt>keytool -delete -alias <old cert alias> -keystore [INSTALL_HOME]/server/conf/ssl.crt/keystore.jks</tt>
			# Import the new certificate:
			#: <tt>keytool -import -v -noprompt -trustcacerts -alias <new cert alias> -file <path to new cert>/newcert.cer -keystore [INSTALL_HOME]/server/conf/ssl.crt/keystore.jks</tt>
			# After importing the new certificate, you will need to restart the server in order for it to take effect.

	== Redirecting HTTP traffic ==		== Redirecting HTTP traffic ==

imported>Dxturner: /* Existing Keys & Certificates */

2015-07-14T21:00:12Z

Existing Keys & Certificates

← Older revision		Revision as of 21:00, 14 July 2015
Line 42:		Line 42:
	#: You will be prompted to set a password, this '''must''' be set - do not leave blank. If you do not have any intermediate certificates then leave out the <tt>-CAfile</tt>, <tt>-caname</tt>, and <tt>-chain</tt> options.		#: You will be prompted to set a password, this '''must''' be set - do not leave blank. If you do not have any intermediate certificates then leave out the <tt>-CAfile</tt>, <tt>-caname</tt>, and <tt>-chain</tt> options.
	# Create a JKS from the <tt>combined.p12</tt> file generated above:		# Create a JKS from the <tt>combined.p12</tt> file generated above:
	#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype ~~PCKS12~~ -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>		#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PKCS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
	#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).		#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
	# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below to ''Enable SSL & Installing the Keystore''.		# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below to ''Enable SSL & Installing the Keystore''.

imported>Jason.nicholls: 1 revision

2015-04-30T10:59:28Z

1 revision

← Older revision	Revision as of 10:59, 30 April 2015
(No difference)

imported>Jason.nicholls: /* Existing Keys & Certificates */

2015-03-20T09:08:38Z

Existing Keys & Certificates

New page

{{DISPLAYTITLE:SSL Configuration}}
[[Category:AppBoard 2.6]]
== Overview ==

For security reasons it's recommended to run AppBoard over SSL (Secure Socket Layer). This will ensure all communications between clients (browsers) and the AppBoard server are encrypted.

By default AppBoard is configured with SSL disabled, but it does ship with a self-signed server certificate and can easily be enabled. In production environments this certificate should be replaced with one issued by a known Certificate Authority (CA) or one signed by a trusted root certificate within the organization.

== Configuring AppBoard for SSL ==

The overall process involves:

# Obtaining a signed certificate:
## Pick a Certificate Authority, this may be in-house if the organization has a Standard Operating Environment with their own root certificate installed on all systems. Otherwise this would be a commercial CA such as VeriSign, Thawte, or Go Daddy.
## Create a private key and Certificate Signing Request (CSR)
## Have the CA sign the request
## Download the signed certificate from the CA. Depending on the CA a variety of formats may be on offer. Choose an appropriate format for Tomcat - which the CA may explicitly list as an option, otherwise choose PKCS#7 format. Other formats may require additional conversion steps before Tomcat can make use of it.
# Alternatively create a self-signed certificate. However, end-users will be presented with certificate errors and warnings as the certificate is not signed by a trusted authority.
# Create a Java KeyStore (JKS) from the private key, signed certificate, and any intermediate certificates from the CA.
# Install they keystore file on the AppBoard server.

{{Note|Due to the large variety of certificate authorities and key/certificate formats, this documentation does not cover all possibilities. If following instructions found elsewhere make sure to install the resulting keystore correctly for AppBoard (see the ''Enable SSL & Install the Keystore'' section).}}

=== Certificate & Keystore ===

For SSL Tomcat requires a Java keystore containing the private key, signed certificate, and any intermediate certificates from the CA. To create and work with a keystore it is necessary to have Java installed and be able to run the <tt>keytool</tt> command.

==== New Certificates ====
The recommended approach is to use <tt>keytool</tt> to create the private key, CSR, and keystore. The CA with then sign and provide a signed certificate along with their own certificate chain which can be imported into the keystore. Most CAs have this process well documented for popular web server platforms. Just follow the instructions for Tomcat such as these from VeriSign - and remember to refer back to this documentation on installing the keystore:

# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&id=AR227 creating a CSR and submitting for signing] (using keytool and creating a keystore in the process).
# [https://knowledge.verisign.com/support/ssl-certificates-support/index?page=content&actp=CROSSLINK&id=AR153 importing the signed certificate into a JKS keystore] (in PKCS#7 / .p7b format)
# Then follow the instructions below on ''Enable SSL & Installing the Keystore''

==== Existing Keys & Certificates ====
A limitation of keytool is that existing private keys cannot be imported. So for situations with an '''existing private key''', and regardless of the certificate format then it will be necessary to use <tt>openssl</tt> to do conversion.

For existing private key with signed certificate and intermediate certificates in X.509 format follow these steps:

# Convert the private key (''private.key''), signed certificate (''server_signed.crt''), and intermediate certificates (''ca.crt'') into PKCS#12 format:
#: <tt>openssl pkcs12 -export -in ''server_signed.crt'' -inkey ''private.key'' -CAfile ''ca.crt'' -caname root -chain -out combined.p12 -name ''your-alias''</tt>
#: You will be prompted to set a password, this '''must''' be set - do not leave blank. If you do not have any intermediate certificates then leave out the <tt>-CAfile</tt>, <tt>-caname</tt>, and <tt>-chain</tt> options.
# Create a JKS from the <tt>combined.p12</tt> file generated above:
#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below to ''Enable SSL & Installing the Keystore''.

For existing private key with signed certificate and intermediate certificates in PKCS#7 (.p7b) format follow these steps:
# Convert the PKCS7 file (''certs.p7b'') to PEM encoded certificates:
#: <tt>openssl pkcs7 -in ''certs.p7b'' -inform DER -print_certs -out ''certs.crt''</tt>
# Convert the private key (''private.key'') and certificates (''certs.crt'' from above):
#: <tt>openssl pkcs12 -export -in ''certs.crt'' -inkey ''private.key'' -out combined.p12 -name ''your-alias''</tt>
#: You will be prompted to set a password, this '''must''' be set - do not leave blank.
# Create a JKS from the <tt>combined.p12</tt> file generated above:
#: <tt>keytool -importkeystore -srckeystore combined.p12 -srcstoretype PCKS12 -alias ''your-alias'' -destkeystore ''your-keystore.jks''</tt>
#: You will be prompted for the password set above and a new password, you '''must''' use the same password. ''your-alias'' must match the alias set in step (1).
# Take the resulting JKS file (<tt>''your-keystore.jks''</tt>) and follow the instructions below to ''Enable SSL & Installing the Keystore''.

=== Enable SSL & Install the Keystore ===

Once a valid keystore has been created it can be installed on the AppBoard server:

# copy to the <tt>[INSTALL_HOME]/server/conf/ssl.crt/</tt> directory. By default files in this directory are automatically included in full archives.
# Edit <tt>setenv-custom.sh|.bat</tt> and:
## update the <tt>KEYSTORE_FILE</tt> and <tt>KEYSTORE_PASS</tt> as required. Please note the keystore file path is relative to <tt>[INSTALL_HOME]/server/</tt>
## update the <tt>KEYSTORE_TYPE</tt> if using something other than Java KeyStore (JKS) format.
## set the <tt>HTTP_SSL</tt> option to <tt>true</tt>.
## (optionally) set the <tt>HTTP_PORT</tt> to the desired port.
# Restart the AppBoard server.

See the [[appboard/2.6/admin/runtime_options|Runtime Options]] page for complete information on all runtime options.

== Redirecting HTTP traffic ==

There are two recommended approaches for redirecting standard HTTP traffic to HTTPS:

# Use an external tool to redirect the traffic such as a load balancer or a full featured HTTP server like [http://httpd.apache.org/ Apache]. For many this will be the preferred option as since no configuration changes to enPortal/AppBoard are necessary.

# Modify <tt>server/conf/server.xml</tt> and <tt>server/webapps/enportal/WEB-INF/web.xml</tt> to define an extra non-SSL connector that will redirect to the HTTPS port. This approach is [https://www.google.com/search?q=tomcat+web.xml+http+connector+forward+https&oq=tomcat+web.xml+http+connector+forward+https&aqs=chrome..69i57.12323j0j7&sourceid=chrome&es_sm=91&ie=UTF-8#q=tomcat+redirect+http+to+https&safe=active well documented by the Tomcat user community].

== Additional Topics ==

* [[appboard/2.6/admin/untrusted_ssl_ios|Untrusted Certificates on iOS mobile devices]]
* [[appboard/2.6/admin/client_certificates|Client Certificates / Client Authentication]]

Appboard/2.6/admin/ssl configuration - Revision history

imported>Mike.berman: 1 revision: Certificate update instructions

imported>Cmace: /* Configuring AppBoard for SSL */

imported>Dxturner: /* Existing Keys & Certificates */

imported>Jason.nicholls: 1 revision

imported>Jason.nicholls: /* Existing Keys & Certificates */