Date: Thu, 28 Mar 2024 19:40:45 -0400 (EDT) Message-ID: <1719255558.840.1711669245837@prodopencatalystconfluence.catalyst> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_839_158397678.1711669245833" ------=_Part_839_158397678.1711669245833 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Optional Step
This step is optional for remote sites.
By default, our recommendation for a typical remote site is to have it s=
ubmit a Certificate Signing Request (CSR) to the certificate authority (CA)=
of the SHRINE network to which they are joining. The CA will in turn gener=
ate a new certificate for the downstream site, and we will return that cert=
ificate, the hub certificate, and the CA certificate of the tier back to th=
e downstream site. The site will then import the certificates into their sh=
rine keystore file, and configure their shrine.conf
and =
server.xml
to point to the alias entry in the keystore that correspo=
nds to the site.
A typical keystore after importing all the certs in would look like this=
(assuming that the downstream site is called "shrine.example.edu"):
Keystore type: jk= s Keystore provider: SUN Your keystore contains 3 entries shrine.example.edu, Oct 31, 2018, PrivateKeyEntry,=20 Certificate fingerprint (SHA1): 26:0B:FE:98:21:BA:C8:5A:A5:F5:35:79:8E:81:1= A:E9:F4:3B:FF:56 shrine-act-test-ca, Jul 31, 2019, trustedCertEntry,=20 Certificate fingerprint (SHA1): 13:4D:B5:5C:E3:48:A0:7B:9B:20:22:8B:0B:C1:B= E:DD:B9:E4:1B:AD shrine-act-test.hms.harvard.edu, Jul 31, 2019, trustedCertEntry,=20 Certificate fingerprint (SHA1): 52:82:A0:6D:D1:48:B2:EA:BB:2C:58:BD:E5:C7:3= B:21:75:2B:46:F6
shrine.conf
contains a block like this:
keystore { file =3D "/opt/shrine/shrine.keystore" password =3D "xxxxxx" privateKeyAlias =3D "shrine.example.edu" keyStoreType =3D "JKS" caCertAliases =3D ["shrine-act-test-ca"] }
And server.xml
will contain a block like this:
<Connector port= =3D"6443" protocol=3D"org.apache.coyote.http11.Http11NioProtocol" maxThreads=3D"150" SSLEnabled=3D"true" scheme=3D"https" secu= re=3D"true" clientAuth=3D"false" sslProtocol=3D"TLS" keystoreFile=3D"/opt/shrine/shrine.keystore" keystorePass=3D"xxxxxx" keyAlias=3D"shrine.example.edu"/>
When using the above approach a web browser attempting to access a shrin= e host configured in this way will generate a warning. The browser will not= trust the CA because none of the CAs are public. Consequently, any certifi= cate that the CA signs is not trusted by the browser. While the browser can= be configured to ignore the warning and the CA can be manually imported in= to the browser's trust store, some downstream sites may opt for a more eleg= ant approach. Using a third-party-signed certificate eliminates the warning= s from the web browser; the root and intermediate CAs are already trusted b= y the browser.
A third-party certificate does not replace the network CA-signe= d certificate; the network CA-signed certificate is still required for sign= ing all application-specific messages. This wiki does not attempt to cover = any vendor-specific processes or output files, because those can vary over = time and across industry. It is up to each remote site that chooses this op= tion to work with its vendor on any necessary technical details.
This guide also assumes the possibility that a site may initially opt fo=
r network CA-signed certificate, but later switch over to a third-party cer=
tificate. For all examples used in our illustration below this guide uses a=
fictitious remote site called shrine.example.edu
.
The first step for the remote site is to generate a certificate signing =
request (CSR) using a private key, and to send that CSR to an SSL/TLS vendo=
r such as InCommon and Symantec. This step can be performed using either keytool
. The vendor will in turn generat=
e a certificate for the requested fully-qualified domain name (FQDN), and i=
t may provide additional certificates for its root and intermediate CAs. Th=
e remote site should work with the vendor to concatenate all certificates t=
ogether into one file, so that it would be possible to trace the chain of t=
rust from the endpoint certificate all the way back to the root CA.
The next step is to ensure that the private key that was used to generat=
e the CSR is in a separate file. If a utility such as openssl
=
was used to generate the CSR, then a file containing the private key should=
already be present and this step is unnecessary. If, however, the site use=
d keytool
to generate the CSR, then the following commands sho=
uld be run to extract the private key from the keystore into a separate fil=
e. Execute the following commands to extract the private key into a file ca=
lled private_key.pem
(the command below assumes that the keyst=
ore is called shrine.keystore
):
$ keytool -import= keystore -srckeystore shrine.keystore -srcstorepass <source_keystore_pas= sword> -srcalias shrine.example.edu -destalias shrine.example.edu -destk= eystore shrine.keystore.p12 -deststoretype PKCS12 -deststorepass <destin= ation_keystore_password> $ openssl pkcs12 -in shrine.keystore.p12 -nodes -nocerts -out private_key.p= em
This private key should be guarded carefully. Ideal places include an en=
crypted disk volume and non-persistent, RAM-based disk (such as /dev/=
shm
in CentOS or Debian). The key can also be stored in an offline a=
nd physically secure location.
Next, upon receiving the signed certificate from the third-party CA, the=
remote site should then bundle the private key with the chained certificat=
es into a PKCS12 file (.pfx
or .p12
suffix) so th=
at SHRINE can verify the chain of trust from the endpoint certificate all t=
he way back to the root CA. Without this trust verification, SHRINE will be=
unable to use the certificates as intended. For our purpose, the PKCS#12 f=
ile format is ideal because it can combine a private key with all correspon=
ding chained certificates into a single entry in the file, and because the =
format is accessible by both openssl
and keytool
.=
In the following command (again, assuming that the private key file is cal=
led private_key.pem
), the certificates_file
conta=
ins the new endpoint certificate plus all intermediate certificates plus th=
e root certificate, and the ca_file
contains only the intermed=
iate certificates plus the root certificate. Run this command to bundle the=
private key, the endpoint certificate, and all intermediate and root certi=
ficates into one single entry within the PKCS12 store:
$ openssl pkcs12 = -export -in <certificates_file> -inkey private_key.pem -out shrine.ke= ystore.p12.temp -name shrine.example.edu-https -CAfile <ca_file> -cha= in -password pass:<your_pkcs12_file_password>
Note here that the value of the -name
field is "shrine.exam=
ple.edu-https". The reason is that we will eventually be importing this ent=
ire entry back into the main Java keystore where another entry called shrine.example.edu
already exists. Recalling our earlier discussion=
about the purposes of certificates, we note that shrine.example.edu<=
/code> entry is responsible for application message signing, while
sh=
rine.example.edu-https
entry is responsible for web browser encrypti=
on. Therefore two distinct keystore entries are necessary.
The newly constructed PKCS12 file should now be imported into the origin=
al shrine.keystore
. Execute the following command, and if prom=
pted to overwrite existing entry, answer "yes":
$ keytool -import= keystore -srckeystore shrine.keystore.p12.temp -srcstoretype pkcs12 -srcsto= repass <your_pkcs12_file_password> -srcalias shrine.example.edu-https= -destkeystore shrine.keystore -deststoretype jks -deststorepass <your_d= estination_keystore_password> -destalias shrine.example.edu-https
Once the import is completed, your shrine.keystore should now look like = this:
Keystore type: jk= s Keystore provider: SUN Your keystore contains 4 entries shrine.example.edu, Oct 31, 2018, PrivateKeyEntry,=20 Certificate fingerprint (SHA1): 26:0B:FE:98:21:BA:C8:5A:A5:F5:35:79:8E:81:1= A:E9:F4:3B:FF:56 shrine.example.edu-https, Jul 31, 2019, PrivateKeyEntry,=20 Certificate fingerprint (SHA1): EF:AF:5E:D3:1A:97:AA:F2:6D:50:B8:9A:23:98:B= 5:2C:0C:18:C3:4B shrine-act-test-ca, Jul 31, 2019, trustedCertEntry,=20 Certificate fingerprint (SHA1): 13:4D:B5:5C:E3:48:A0:7B:9B:20:22:8B:0B:C1:B= E:DD:B9:E4:1B:AD shrine-act-test.hms.harvard.edu, Jul 31, 2019, trustedCertEntry,=20 Certificate fingerprint (SHA1): 52:82:A0:6D:D1:48:B2:EA:BB:2C:58:BD:E5:C7:3= B:21:75:2B:46:F6
Notice that there are now two (2) entries associated with shrine.example=
.edu: the original one continues to be used for application signing, and we=
will configure the "-https
" entry for use by Tomcat to encryp=
t web browser traffic.
Next, configure the alias entry in Tomcat's server.xml
to p=
oint to the newly imported, third-party-generated certificate:
<Connector port= =3D"6443" protocol=3D"org.apache.coyote.http11.Http11NioProtocol" maxThreads=3D"150" SSLEnabled=3D"true" scheme=3D"https" secu= re=3D"true" clientAuth=3D"false" sslProtocol=3D"TLS" keystoreFile=3D"/opt/shrine/shrine.keystore" keystorePass=3D"xxxxxxxxxx" keyAlias=3D"shrine.example.edu-https"/>
Once all configuration files have been updated, restart Tomcat. If every= thing has been configured properly, you should no longer see any warning me= ssages from your browser regarding untrusted certificates when accessing yo= ur SHRINE host.