diff --git a/docs/administration-guide/src/main/asciidoc/jvm.adoc b/docs/administration-guide/src/main/asciidoc/jvm.adoc index 2ff90b4775c..3225a097401 100644 --- a/docs/administration-guide/src/main/asciidoc/jvm.adoc +++ b/docs/administration-guide/src/main/asciidoc/jvm.adoc @@ -102,11 +102,14 @@ asadmin> list-jvm-options -XX: UnlockDiagnosticVMOptions -Dcom.sun.enterprise.config.config_environment_factory_class=com.sun.enterprise. config.serverbeans.AppserverConfigEnvironmentFactory --Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks +-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.p12 -XX:NewRatio=2 -Djava.security.policy=${com.sun.aas.instanceRoot}/config/server.policy -Djdbc.drivers=org.apache.derby.jdbc.ClientDriver --Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks +-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.p12 + +# NOTE: PKCS12 format (.p12) is recommended. For legacy compatibility, +# JKS format (.jks) is also supported. -client -Djava.ext.dirs=${com.sun.aas.javaRoot}/lib/ext${path.separator}${com.sun.aas.ja vaRoot}/jre/lib/ext${path.separator}${com.sun.aas.instanceRoot}/lib/ext${path.se diff --git a/docs/application-development-guide/src/main/asciidoc/java-clients.adoc b/docs/application-development-guide/src/main/asciidoc/java-clients.adoc index 65aa9b44274..04172dee515 100644 --- a/docs/application-development-guide/src/main/asciidoc/java-clients.adoc +++ b/docs/application-development-guide/src/main/asciidoc/java-clients.adoc @@ -571,7 +571,9 @@ organization does not already have one. 3. Replace the {productName} self-signed certificate with the trusted certificate by importing the trusted certificate into the {productName} keystore using the `s1as` alias. By default, the -keystore is located at domain-dir`/config/keystore.jks`. +keystore is located at domain-dir`/config/keystore.p12` (PKCS12 format, +recommended). For legacy compatibility, JKS format keystores +(`keystore.jks`) are also supported. + For more information about importing a trusted certificate into the domain keystore, see "xref:security-guide.adoc#administering-jsse-certificates[Administering JSSE Certificates]" diff --git a/docs/ha-administration-guide/src/main/asciidoc/instances.adoc b/docs/ha-administration-guide/src/main/asciidoc/instances.adoc index 1e84624052d..f6483d94dfd 100644 --- a/docs/ha-administration-guide/src/main/asciidoc/instances.adoc +++ b/docs/ha-administration-guide/src/main/asciidoc/instances.adoc @@ -1662,11 +1662,13 @@ By default, {productName} synchronizes only the following configuration files: * `admin-keyfile` +* `cacerts.p12` * `cacerts.jks` * `default-web.xml` * `domain.xml` * `domain-passwords` * `keyfile` +* `keystore.p12` * `keystore.jks` * `server.policy` * `sun-acc.xml` @@ -1701,12 +1703,12 @@ addition to the files that {productName} resynchronizes by default: [source] ---- admin-keyfile -cacerts.jks +cacerts.p12 default-web.xml domain.xml domain-passwords keyfile -keystore.jks +keystore.p12 server.policy sun-acc.xml wss-server-config-1.0.xml diff --git a/docs/reference-manual/src/main/asciidoc/create-domain.adoc b/docs/reference-manual/src/main/asciidoc/create-domain.adoc index 63613137d51..a00b5182c08 100644 --- a/docs/reference-manual/src/main/asciidoc/create-domain.adoc +++ b/docs/reference-manual/src/main/asciidoc/create-domain.adoc @@ -146,8 +146,10 @@ When the `--portbase` option is specified, the output of this domain is contacted by a web browser over a secure channel (HTTPS), this certificate is presented by the domain. The master password is supposed to protect the store (a file) that contains this certificate. - This file is called `keystore.jks` and is created in the configuration - directory of the domain created. If however, this option is chosen, + This file is called `keystore.p12` (PKCS12 format) and is + created in the configuration directory of the domain created. For legacy + compatibility, JKS format (`keystore.jks`) is also supported. If however, + this option is chosen, the master password is saved on the disk in the domain's configuration location. The master password is stored in a file called `master-password`, which is a Java JCEKS type keystore. The reason for diff --git a/docs/reference-manual/src/main/asciidoc/list-jvm-options.adoc b/docs/reference-manual/src/main/asciidoc/list-jvm-options.adoc index df10a2cf363..2558a5b601e 100644 --- a/docs/reference-manual/src/main/asciidoc/list-jvm-options.adoc +++ b/docs/reference-manual/src/main/asciidoc/list-jvm-options.adoc @@ -77,12 +77,15 @@ asadmin> list-jvm-options -XX: UnlockDiagnosticVMOptions -Dcom.sun.enterprise.config.config_environment_factory_class= com.sun.enterprise.config.serverbeans.AppserverConfigEnvironmentFactory --Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks +-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.p12 -XX:NewRatio=2 -DANTLR_USE_DIRECT_CLASS_LOADING=true -Djava.security.policy=${com.sun.aas.instanceRoot}/config/server.policy -Djdbc.drivers=org.apache.derby.jdbc.ClientDriver --Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks +-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.p12 + +# NOTE: PKCS12 format (.p12) is recommended. For legacy compatibility, +# JKS format (.jks) is also supported. -client -Djava.ext.dirs=${com.sun.aas.javaRoot}/lib/ext${path.separator}${ com.sun.aas.javaRoot}/jre/lib/ext${path.separator}${com.sun.aas.instanceRoot} diff --git a/docs/security-guide/src/main/asciidoc/administrative-security.adoc b/docs/security-guide/src/main/asciidoc/administrative-security.adoc index 8041d5dde56..529f893c102 100644 --- a/docs/security-guide/src/main/asciidoc/administrative-security.adoc +++ b/docs/security-guide/src/main/asciidoc/administrative-security.adoc @@ -239,9 +239,11 @@ self-signed certificate for remote instances. Then, when you enable secure admin, the following actions are performed: -* Both private keys are stored in the domain-wide DAS keystore file, keystore.jks. +* Both private keys are stored in the domain-wide DAS keystore file, keystore.p12 + (PKCS12 format, recommended). For legacy compatibility, keystore.jks (JKS format) is also supported. * Both public certificates are stored in the domain-wide DAS truststore - file, cacerts.jks. + file, cacerts.p12 (PKCS12 format, recommended). For legacy compatibility, + cacerts.jks (JKS format) is also supported. When the DAS sends a message to an instance: @@ -286,7 +288,7 @@ change it with the `change-master-password` subcommand. [source] ---- -keytool -list -keystore keystore.jks +keytool -list -keystore keystore.p12 Enter keystore password: Keystore type: JKS Keystore provider: SUN @@ -460,7 +462,7 @@ the `s1as` alias before doing so. If you decide to use the `s1as` and `glassfish-instance` aliases with your own certificates, you will first need to disable secure admin (if enabled) and then change or delete the exiting `s1as` alias from both -the `keystore.jks` keystore and `cacerts.jks` truststore for the DAS. +the `keystore.p12` keystore and `cacerts.p12` truststore for the DAS. You can use the `--changealias` or `--delete` option of `keytool` to accomplish this. Then, import your own certificates. @@ -514,7 +516,7 @@ you can use keytool to display the DN of a certificate: [source] ---- -keytool -v -list -keystore keystore.jks +keytool -v -list -keystore keystore.p12 Enter keystore password: Keystore type: JKS Keystore provider: SUN @@ -597,7 +599,7 @@ truststore, you can use keytool to display the alias of a certificate: [source] ---- -keytool -v -list -keystore cacerts.jks +keytool -v -list -keystore cacerts.p12 Enter keystore password: Keystore type: JKS Keystore provider: SUN diff --git a/docs/security-guide/src/main/asciidoc/running-in-secure-environment.adoc b/docs/security-guide/src/main/asciidoc/running-in-secure-environment.adoc index ee062ced508..6beaf12e009 100644 --- a/docs/security-guide/src/main/asciidoc/running-in-secure-environment.adoc +++ b/docs/security-guide/src/main/asciidoc/running-in-secure-environment.adoc @@ -202,10 +202,10 @@ The database files. {productName} includes Apache Derby database, however, you can use any JDBC-compliant database. The directory and filename location of a private keystore, such as -keystore.jks +keystore.p12. The directory and filename location of a Root Certificate Authority (CA) -keystore, such as cacerts.jks. +keystore, such as cacerts.p12. For example, operating systems provide utilities such as umask and chmod to set the file access permissions. At a minimum, consider using "umask diff --git a/docs/security-guide/src/main/asciidoc/system-security.adoc b/docs/security-guide/src/main/asciidoc/system-security.adoc index d61fec0abce..c323f6b1564 100644 --- a/docs/security-guide/src/main/asciidoc/system-security.adoc +++ b/docs/security-guide/src/main/asciidoc/system-security.adoc @@ -771,17 +771,22 @@ its certificate information in certificate databases in the domain-dir``/config`` directory: Keystore file:: - The `keystore.jks` file contains {productName} certificate, + The `keystore.p12` file contains {productName} certificate, including its private key. The keystore file is protected with a password. + Each keystore entry has a unique alias. After installation, the - {productName} keystore has a single entry with an alias of `s1as`. + {productName} keystore has a single entry with an alias of `s1as`. + + NOTE: For legacy compatibility, JKS format keystores (`keystore.jks`) + are still supported, but PKCS12 format is recommended as it is the + industry standard and default format since Java 9. Truststore file:: - The `cacerts.jks` file contains the {productName} trusted + The `cacerts.p12` file contains the {productName} trusted certificates, including public keys for other entities. For a trusted certificate, the server has confirmed that the public key in the certificate belongs to the certificate's owner. Trusted certificates - generally include those of CAs. + generally include those of CAs. + + NOTE: For legacy compatibility, JKS format truststores (`cacerts.jks`) + are still supported, but PKCS12 format is recommended. By default, {productName} is configured with a keystore and truststore that will work with the example applications and for @@ -1705,15 +1710,13 @@ path to the utility must be present on the command line. 1. Change to the directory that contains the keystore and truststore files. + Always generate the certificate in the directory containing the keystore and truststore files. The default is domain-dir``/config``. -2. Generate the certificate in the keystore file, `keystore.jks`, using +2. Generate the certificate in the keystore file, `keystore.p12`, using the following command format: + [source] ---- -keytool -genkey -alias keyAlias-keyalg RSA - -keypass changeit - -storepass changeit -keystore keystore.jks +keytool -genkey -alias keyAlias -keyalg RSA -keypass changeit + -storepass changeit -keysize 4096 -keystore keystore.p12 ---- Use any unique name as your keyAlias. If you have changed the keystore or private key password from the default (`changeit`), substitute the @@ -1725,21 +1728,18 @@ A prompt appears that asks for your name, organization, and other information. + [source] ---- -keytool -export -alias keyAlias-storepass changeit - -file server.cer - -keystore keystore.jks +keytool -export -alias keyAlias -storepass changeit + -file server.cer -keystore keystore.p12 ---- 4. If a certificate signed by a certificate authority is required, see xref:#to-sign-a-certificate-by-using-keytool[To Sign a Certificate by Using `keytool`]. -5. Create the `cacerts.jks` truststore file and add the certificate to +5. Create the `cacerts.p12` truststore file and add the certificate to the truststore, using the following command format: + [source] ---- -keytool -import -v -trustcacerts --alias keyAlias - -file server.cer --keystore cacerts.jks +keytool -import -v -trustcacerts -alias keyAlias + -file server.cer -keystore cacerts.p12 -keypass changeit ---- If you have changed the keystore or private key password from the @@ -1754,7 +1754,7 @@ Information similar to the following is displayed: [source] ---- Certificate was added to keystore -[Saving cacerts.jks] +[Saving cacerts.p12] ---- 7. To apply your changes, restart {productName}. See "xref:administration-guide.adoc#to-restart-a-domain[To Restart a Domain]" in {productName} Administration Guide. @@ -1763,6 +1763,9 @@ Certificate was added to keystore Example 1-11 Creating a Self-Signed Certificate in a JKS Keystore by Using an RSA Key Algorithm +NOTE: This example shows the legacy JKS format. For new deployments, +consider using PKCS12 format as shown in Example 1-11a. + RSA is public-key encryption technology developed by RSA Data Security, Inc. @@ -1773,6 +1776,21 @@ keytool -genkey -noprompt -trustcacerts -keyalg RSA -alias ${cert.alias} -storepass ${keystore.pass} ---- +[[ghlii-pkcs12]] +Example 1-11a Creating a Self-Signed Certificate in a PKCS12 Keystore by +Using an RSA Key Algorithm + +PKCS12 is the recommended keystore format and has been the default +since Java 9. RSA is public-key encryption technology developed by +RSA Data Security, Inc. + +[source] +---- +keytool -genkey -noprompt -trustcacerts -keyalg RSA -alias ${cert.alias} +-dname ${dn.name} -keypass ${key.pass} +-keystore ${keystore.file} -storepass ${keystore.pass} +---- + [[ghlew]] Example 1-12 Creating a Self-Signed Certificate in a JKS Keystore by Using a Default Key Algorithm @@ -1826,7 +1844,7 @@ certificate. + [source] ---- -keytool -delete -alias s1as -keystore keystore.jks -storepass +keytool -delete -alias s1as -keystore keystore.p12 -storepass ---- where is the password for the keystore. For example, "mypass". Note that `s1as` is the default alias of the {productName} @@ -1835,7 +1853,7 @@ keystore. + [source] ---- -keytool -genkeypair -keyalg -keystore keystore.jks +keytool -genkeypair -keyalg -keystore keystore.p12 -validity -alias s1as ---- where is the algorithm to be used for generating the key pair, @@ -1855,7 +1873,7 @@ of the certificate does not match the name of the site. + [source] ---- -keytool -certreq -alias s1as -file -keystore keystore.jks +keytool -certreq -alias s1as -file -keystore keystore.p12 -storepass ---- where is the file in which the CSR is stored (for @@ -1873,12 +1891,12 @@ into a file such as `s1as.cert`. Download the CA certificate and any intermediate CA certificates and store them in local files. 6. Import the CA certificate (if not already present) and any intermediate CA certificates (if not already present) indicated by the -CA into the truststore `cacerts.jks`: +CA into the truststore `cacerts.p12`: + [source] ---- keytool -import -v -trustcacerts -alias -file ca.cert - -keystore cacerts.jks -storepass + -keystore cacerts.p12 -storepass ---- 7. Replace the original self-signed certificate with the certificate you obtained from the CA, as stored in a file such as `s1as.cert`: @@ -1886,7 +1904,7 @@ you obtained from the CA, as stored in a file such as `s1as.cert`: [source] ---- keytool -import -v -trustcacerts -alias s1as -file s1as.cert - -keystore keystore.jks -storepass + -keystore keystore.p12 -storepass ---- When you import the certificate using the same original alias `s1as`, keytool treats it as a command to replace the original certificate with diff --git a/docs/security-guide/src/main/asciidoc/user-security.adoc b/docs/security-guide/src/main/asciidoc/user-security.adoc index 621a97e7559..489e60d3506 100644 --- a/docs/security-guide/src/main/asciidoc/user-security.adoc +++ b/docs/security-guide/src/main/asciidoc/user-security.adoc @@ -382,7 +382,10 @@ Use the following syntax: + [source] ---- -keytool -importcert -alias "alias-name" -keystore domain-dir/config/cacerts.jks +keytool -importcert -alias "alias-name" -keystore domain-dir/config/cacerts.p12 ++ ++NOTE: The above examples show PKCS12 format (.p12) which is the recommended ++format since Java 9. For legacy JKS format compatibility, use `.jks` file extension. -file cert-name ---- + @@ -403,7 +406,7 @@ alias called "OID self-signed certificate," you would use the following command: [source] ---- keytool -importcert -alias "OID self signed certificate" -keystore \ -/glassfish7/glassfish/domains/domain1/config/cacerts.jks -file oid.cer +/glassfish7/glassfish/domains/domain1/config/cacerts.p12 -file oid.cer ---- 6. Restart the {productName} domain. + See "xref:administration-guide.adoc#to-restart-a-domain[To Restart a Domain]" @@ -471,7 +474,10 @@ Use the following syntax: + [source] ---- -keytool -importcert -alias "alias-name" -keystore domain-dir/config/cacerts.jks +keytool -importcert -alias "alias-name" -keystore domain-dir/config/cacerts.p12 ++ ++NOTE: The above examples show PKCS12 format (.p12) which is the recommended ++format since Java 9. For legacy JKS format compatibility, use `.jks` file extensions. -file cert-name ---- + @@ -492,7 +498,7 @@ alias called "OVD self-signed certificate," you would use the following command: [source] ---- keytool -importcert -alias "OVD self signed certificate" -keystore \ -/glassfish7/glassfish/domains/domain1/config/cacerts.jks -file ovd.cer +/glassfish7/glassfish/domains/domain1/config/cacerts.p12 -file ovd.cer ---- 5. Restart the {productName} domain. + See "xref:administration-guide.adoc#to-restart-a-domain[To Restart a Domain]" diff --git a/docs/troubleshooting-guide/src/main/asciidoc/specific-issues.adoc b/docs/troubleshooting-guide/src/main/asciidoc/specific-issues.adoc index 3e573ed01f1..701cc867c81 100644 --- a/docs/troubleshooting-guide/src/main/asciidoc/specific-issues.adoc +++ b/docs/troubleshooting-guide/src/main/asciidoc/specific-issues.adoc @@ -765,6 +765,6 @@ the following value: [source] ---- --Djavax.net.ssl.keyStore=${admin.domain.dir}/${admin.domain}/config/keystore.jks --Djavax.net.ssl.trustStore=${admin.domain.dir}/${admin.domain}/config/cacerts.jks +-Djavax.net.ssl.keyStore=${admin.domain.dir}/${admin.domain}/config/keystore.p12 +-Djavax.net.ssl.trustStore=${admin.domain.dir}/${admin.domain}/config/cacerts.p12 ----