JBoss Web - Aanmaken CSR

Voor het aanvragen van een SSL certificaat is een Certificate Signing Request (CSR) nodig. Genereer de CSR samen met de Private Key op de webserver. Vul voor een wildcard certificaat als CN (Common Name) een * (asterisk) in in plaats van het subdomein, bijvoorbeeld *.sslcertificaten.nl (en geen www.sslcertificaten.nl).

Let op: Deze handleiding refereert aan het gebruik van JSSE, dat geleverd wordt met JDK 1.5 en hoger. Als u APR gebruikt, werkt JBoss Web met OpenSSL, wat een andere configuratie hanteert.

Bereid de Certificate Keystore voor

JBoss Web werkt op dit moment alleen onder JKS, PKCS11 of PKCS12 formaat keystores. Het JKS formaat is Java's standaard "Java KeyStore" formaat, en is het formaat gecreëerd door de keytool command-line tool. Deze tool zit in de JDK. Het PKCS12 formaat is een internet standaard, en kan worden bewerkt via onder andere OpenSSL en Microsoft's Key-Manager. Elke invoer in een keystore wordt geïdentificeerd door een alias string. Hoewel veel keystore implementaties niet hoofdlettergevoelig zijn, is dit wel beschikbaar. De PKCS11 specificatie bijvoorbeeld, vereist dat aliassen hoofdlettergevoelig zijn. Om problemen, gerelateerd aan tekengevoeligheid, te vermijden wordt het afgeraden aliassen te gebruiken die alleen verschillen in het hoofdlettergebruik. Om een bestaand certificaat in een JKS keystore te importeren, lees de documentatie (in uw JDK documentatie) over keytool. De beschrijving hieronder gebruikt de variabele naam $CATALINA_HOME om te refereren naar de directory waarin u JBoss Web heeft geïnstalleerd en is de basis directory vanwaar alle relatieve paden komen. Echter, als u JBoss Web voor multiple instances heeft geconfigureerd door een CATALINA_BASE directory in te stellen, dient u $CATALINA_BASE te gebruiken in plaats van $CATALINA_HOME voor elk van de referenties.

OpenSSL zet vaak leesbare tekst voor de key en keytool ondersteunt dit niet.  Haal de OpenSSL tekst weg als deze aanwezig is alvorens de key te importeren als u gebruik maakt van keytool. Om een bestaand certificaat ondertekend door een eigen CA in een PKCS12 keystore te importeren gebruikmakend van OpenSSL voert u het volgende commando uit:

  openssl pkcs12 -export -in mycert.crt -inkey mykey.key -out mycert.p12 -name tomcat -CAfile myCA.crt -caname root -chain

Om een nieuwe keystore aan te maken die een single self-signed Certificaat bevat, voert u de volgende code uit vanaf een terminal command line:

Windows: 

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA

Unix: 

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA


(Het RSA algoritme heeft de voorkeur en is compatibel met andere servers).

Dit commando zal een nieuw bestand genereren in de home directory van de gebruiker waaronder u deze uitvoert, genaamd ".keystore". Om een andere locatie of bestandsnaam op te geven, voegt u de -keystore parameter gevolgd door het complete pad naar uw keystore bestand aan de keytool toe. U dient ook de nieuwe bestandslocatie toe te voegen aan het server.xml configuratiebestand. Bijvoorbeeld:

Windows:

%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA -keystore \path\to\my\keystore

Unix:

 $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/my/keystore

Vervolgens krijgt u een melding voor het opgeven van een keystore wachtwoord. Het default wachtwoord in JBoss Web is changeit (geen hoofdletters) maar u kunt natuurlijk een ander wachtwoord opgeven. U dient het aangepaste wachtwoord te specificeren in het server.xml configuratiebestand. Hierna wordt u gevraagd algemene informatie op te geven over het certificaat, zoals bedrijfsnaam, naam contactpersoon, etc. Deze informatie zal getoond worden als gebruikers een beveiligde pagina bezoeken op uw website, dus zorg dat alle informatie klopt. Als laatste wordt u om een wachtwoord van de key gevraagd, wat specifiek voor dit Certificaat is (in tegenstelling tot andere Certificaten opgeslagen in dezelfde keystore). U dient hetzelfde wachtwoord te gebruiken als gebruikt is voor het keystore wachtwoord zelf. (Op dit moment zal de keytool melding geven dat het drukken op de ENTER toets dit automatisch voor u doet). Als alles succesvol afgerond is heeft u nu een keystore bestand met een Certificaat dat gebruikt kan worden door uw server.

NB: Uw private key wachtwoord en keystore wachtwoord moeten hetzelfde zijn. Als ze verschillen krijgt u een foutmelding in de vorm van java.io.IOException: Cannot recover key, zoals gedocumenteerd in Bugzilla issue 38217.

Bewerk het JBoss Web Configuratie bestand

Als u gebruik maakt van APR heeft u de optie om een alternatieve engine te configureren aan openSSL. 

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="someengine" SSLRandomSeed="somedevice" />

De default waarde is:


  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" SSLRandomSeed="builtin" />

Om SSL te gebruiken onder APR moet u er wel voor zorgen dat het SSLEngine-attribuut is ingesteld op iets anders dan OFF. De default waarde is ON en als u een andere waarde opgeeft dient dit een geldige engine naam te zijn. Als u geen SSL support heeft gecompileerd in uw Tomcat Native library, dan dient u de initialisatie uit te schakelen. 

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="off" />

De laatste stap is het configureren van de secure socket in het $CATALINA_HOME/conf/server.xml bestand, waarbij $CATALINA_HOME de directory vertegenwoordigd waarin u JBoss Web heeft geïnstalleerd. Een voorbeeld &lt;Connector&gt; element voor een SSL connector is bijgevoegd in het default server.xml bestand. Het zal er dan ongeveer uitzien zoals hieronder:

<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector 
          port="8443" minSpareThreads="5" maxSpareThreads="75"
          enableLookups="true" disableUploadTimeout="true" 
          acceptCount="100"  maxThreads="200"
          scheme="https" secure="true" SSLEnabled="true"
          keystoreFile="${user.home}/.keystore" keystorePass="changeit"
          clientAuth="false" sslProtocol="TLS"/>
--> 

Het voorbeeld hierboven veroorzaakt een fout als u de APR en de Tomcat Native libraries in uw pad heeft staan, omdat Tomcat zal proberen om de APR connector automatisch te laden.
De APR connector gebruikt andere attributen voor SSL keys en certificaten. Een voorbeeld van zo'n configuratie:

<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector
          port="8443" minSpareThreads="5" maxSpareThreads="75"
          enableLookups="true" disableUploadTimeout="true"
          acceptCount="100"  maxThreads="200"
          scheme="https" secure="true" SSLEnabled="true"
          SSLCertificateFile="/usr/local/ssl/server.crt" 
          SSLCertificateKeyFile="/usr/local/ssl/server.pem"
          clientAuth="false" sslProtocol="TLS"/>
--> 

Om auto configuratie te vermijden kunt u aangeven welke connector gebruikt dient te worden door een classname in het protocol attribuut te specificeren. Om een Java connector te definiëren, ongeacht of de APR library geladen is of niet, doe het volgende:

<-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!-- 
<Connector protocol="org.apache.coyote.http11.Http11Protocol"
          port="8443" minSpareThreads="5" maxSpareThreads="75"
          enableLookups="true" disableUploadTimeout="true" 
          acceptCount="100"  maxThreads="200"
          scheme="https" secure="true" SSLEnabled="true"
          keystoreFile="${user.home}/.keystore" keystorePass="changeit"
          clientAuth="false" sslProtocol="TLS"/>
-->

En om een APR connector te specificeren:

<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!-- 
<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
          port="8443" minSpareThreads="5" maxSpareThreads="75"
          enableLookups="true" disableUploadTimeout="true" 
          acceptCount="100"  maxThreads="200"
          scheme="https" secure="true" SSLEnabled="true"
          SSLCertificateFile="/usr/local/ssl/server.crt" 
          SSLCertificateKeyFile="/usr/local/ssl/server.pem"
          clientAuth="false" sslProtocol="TLS"/>
-->

U zult zien dat het Connector element zelf is voorzien van een #. Deze dient u te verwijderen. Hierna kunt u de attributen waar nodig aanpassen.

Het poortnummer (default is 8443) is het TCP/IP poortnummer waarop JBoss Web secure connecties toestaat. Dit kunt u wijzigen naar elk ander poortnummer (zoals de default poort voor https, 443).

Als u hier het poortnummer wijzigt dient u ook de waarde gespecificeerd voor het redirectPort attribuut op de non-SSL connector te wijzigen. Dit zorgt ervoor dat JBoss Web automatisch gebruikers redirect die pogen toegang te krijgen tot een pagina met veiligheidsbeperkingen en dat SSL vereist is, zoals gesteld in de Servlet 2.4 Specificatie.

Er zijn nog extra opties om het SSL protocol te configureren. U dient waardes van de volgende attributen te wijzigen of toe te voegen, afhankelijk van hoe u eerder de keystore heeft geconfigureerd:

Attribuut   Beschrijving
Algorithm Het certificaat encoding algoritme die wordt gebruikt. Default is dit "SunX509". Voor IBM JVM's dient u de waarde "IbmX509" te gebruiken. Voor andere merken raadpleeg de JVM documentatie voor de correcte waarde.
ClientAuth Ingesteld op "true" als u wilt dat de SSL stack een geldige certificaat chain vereist alvorens een connectie te accepteren. Stel in op "want" als u wilt dat de SSL stack een aanvraag doet voor een client Certificaat, maar niet faalt als er geen voorhanden is. De "false" waarde (defaultwaarde) vereist geen certificaat chain, tenzij de gebruiker een verzoek doet voor een bron die is beveiligd en gebruik maakt van CLIENT-CERT authenticatie.
KeystoreFile    De padnaam van het keystore bestand waarin het certificaat is opgeslagen dat geladen dient te worden. Standaard is de padnaam het ".keystore"-bestand in de home directory van de gebruiker waarop JBoss Web draait
KeystorePass  Het wachtwoord dat wordt gebruikt om toegang te krijgen tot het server certificaat van het opgegeven keystore bestand. De default waarde is "changeit".
KeystoreType Het type keystore bestand die wordt gebruikt voor het certificaat. Als deze niet is gespecificeerd dan is de default waarde "JKS". Bijvoorbeeld de *.p12 bestanden van OpenSSL kunnen gebruikt worden door PKCS12 te gebruiken.
SslProtocol De versie van het SSL protocol dat u gebruikt. Als deze niet is gespecificeerd is de default waarde "TLS".
Ciphers Een komma gescheiden lijst van de encryptiegetallen die mogen worden gebruikt. Als deze niet is gespecificeerd mag elk beschikbaar getal worden gebruikt.
KeyAlias De alias die wordt gebruikt voor het certificate in de keystore. Als deze niet is gespecificeerd wordt de eerste key read in de keystore gebruikt.
TruststoreFile Het TrustStore bestand dat de client certificaten valideert.
TruststorePass Het wachtwoord om toegang te krijgen tot de TrustStore. Dit wachtwoord wordt de default waarde voor keystorePass.
TruststoreType Voeg dit element toe als u gebruik maakt van een andere formaat voor de TrustStore dan die u gebruikt voor de KeyStore.


   
Nadat u deze configuratiewijzigingen heeft doorgevoerd dient u de JBoss Web te herstarten zoals u normaal doet en dan zou alles moeten werken. U zou nu toegang moeten krijgen tot elke webapplicatie ondersteund door JBoss Web via SSL. Bijvoorbeeld, probeer:

https://localhost:8443

U ziet nu de gebruikelijke JBoss Web splash pagina (behalve als u de ROOT web applicatie heeft aangepast).

Troubleshooting   

Hier is een lijst van veel voorkomende problemen die u tegen kunt komen als u SSL instelt en wat u er aan kunt doen.

Probleem: Ik krijg "java.security.NoSuchAlgorithmException" fouten in mijn log bestanden.
Oplossing: De JVM kan de JSSE JAR bestanden niet vinden. Volg de instructies voor het downloaden en installeren van JSSE.

Probleem: Als JBoss Web opstart, krijg ik de uitzondering "java.io.FileNotFoundException: {some-directory}/{some-file} not found".
Oplossing: Een mogelijke verklaring is dat JBoss Web de keystore niet kan vinden op de plek waar het kijkt. Standaard verwacht JBoss Web het keystore bestand genaamd .keystore in de user home directory waaronder JBoss Web draait (welke wel of niet dezelfde is als de uwe). Als het keystore bestand ergens anders staat dan dient u een keystoreFile attribute toe te voegen aan het <Factory> element in het JBoss Web configuratie bestand.

Probleem: Als JBoss Web opstart, krijg ik de uitzondering "java.io.FileNotFoundException: Keystore was tampered with, or password was incorrect".
Oplossing: Ervanuitgaande dat niemand uw keystore bestand heeft veranderd is de meest voor de hand liggende oorzaak dat JBoss Web een ander wachtwoord gebruikt dan degene die u gebruikt heeft om het keystore bestand aan te maken. Om dit te herstellen kunt u opnieuw het keystore bestand aanmaken of u kunt het keystorePass attribuut toevoegen of updaten in het <Connector> element in het JBoss Web configuratie bestand.
LET OP: Wachtwoorden zijn hoofdlettergevoelig!

Probleem: Als JBoss Web opstart, krijg ik de uitzondering "java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No available certificate or key corresponds to the SSL cipher suites which are enabled."
Oplossing: Een mogelijke verklaring is dat JBoss Web de alias voor de server key in de gespecificeerde keystore niet kan vinden. Controleer of de correcte keystoreFile en keyAlias zijn gespecificeerd in het <Connector> element in het JBoss Web configuratiebestand.
LET OP: keyAlias waarden kunnen hoofdlettergevoelig zijn!

Kopieer de volledige inhoud van de aangemaakte CSR, inclusief begin- en eindregels, om een certificaat te bestellen. 

Certificaat aanvragen

SSLCheck

De SSLCheck controleert of je certificaat goed op je server is geïnstalleerd en of er mogelijke problemen zijn.