Merge

src/java.base/share/man/java.1

@@ -1813,6 +1813,30 @@ is needed.
 .PP
 You can specify values for multiple parameters by separating them with a
 comma.
+Event settings and .jfc options can be specified using the following
+syntax:
+.TP
+.B \f[CB]option=\f[R]\f[I]value\f[R]
+Specifies the option value to modify.
+To list available options, use the \f[CB]JAVA_HOME\f[R]/bin/jfr tool.
+.RS
+.RE
+.TP
+.B \f[CB]event\-setting\f[R]=\f[I]value\f[R]
+Specifies the event setting value to modify.
+Use the form: #= To add a new event setting, prefix the event name with
+\[aq]+\[aq].
+.RS
+.RE
+.PP
+You can specify values for multiple event settings and .jfc options by
+separating them with a comma.
+In case of a conflict between a parameter and a .jfc option, the
+parameter will take precedence.
+The whitespace delimiter can be omitted for timespan values, i.e.
+20ms.
+For more information about the settings syntax, see Javadoc of the
+jdk.jfr package.
 .RE
 .TP
 .B \f[CB]\-XX:ThreadStackSize=\f[R]\f[I]size\f[R]

src/java.base/share/man/keytool.1

@@ -22,7 +22,7 @@
 .\"t
 .\" Automatically generated by Pandoc 2.3.1
 .\"
-.TH "KEYTOOL" "1" "2021" "JDK 17\-ea" "JDK Commands"
+.TH "KEYTOOL" "1" "2021" "JDK 17" "JDK Commands"
 .hy
 .SH NAME
 .PP
@@ -382,6 +382,10 @@ For example, an Elliptic Curve name.
 .IP \[bu] 2
 {\f[CB]\-sigalg\f[R] \f[I]alg\f[R]}: Signature algorithm name
 .IP \[bu] 2
+{\f[CB]\-signer\f[R] \f[I]alias\f[R]}: Signer alias
+.IP \[bu] 2
+[\f[CB]\-signerkeypass\f[R] \f[I]arg\f[R]]: Signer key password
+.IP \[bu] 2
 [\f[CB]\-dname\f[R] \f[I]name\f[R]]: Distinguished name
 .IP \[bu] 2
 {\f[CB]\-startdate\f[R] \f[I]date\f[R]}: Certificate validity start date
@@ -417,16 +421,21 @@ with an optional configure argument.
 .PP
 Use the \f[CB]\-genkeypair\f[R] command to generate a key pair (a public
 key and associated private key).
-Wraps the public key in an X.509 v3 self\-signed certificate, which is
-stored as a single\-element certificate chain.
-This certificate chain and the private key are stored in a new keystore
-entry that is identified by its alias.
+When the \f[CB]\-signer\f[R] option is not specified, the public key is
+wrapped in an X.509 v3 self\-signed certificate and stored as a
+single\-element certificate chain.
+When the \f[CB]\-signer\f[R] option is specified, a new certificate is
+generated and signed by the designated signer and stored as a
+multiple\-element certificate chain (containing the generated
+certificate itself, and the signer???s certificate chain).
+The certificate chain and private key are stored in a new keystore entry
+that is identified by its alias.
 .PP
 The \f[CB]\-keyalg\f[R] value specifies the algorithm to be used to
 generate the key pair, and the \f[CB]\-keysize\f[R] value specifies the
 size of each key to be generated.
 The \f[CB]\-sigalg\f[R] value specifies the algorithm that should be used
-to sign the self\-signed certificate.
+to sign the certificate.
 This algorithm must be compatible with the \f[CB]\-keyalg\f[R] value.
 .PP
 The \f[CB]\-groupname\f[R] value specifies the named group (for example,
@@ -435,9 +444,30 @@ generated.
 Only one of \f[CB]\-groupname\f[R] and \f[CB]\-keysize\f[R] can be
 specified.
 .PP
+The \f[CB]\-signer\f[R] value specifies the alias of a
+\f[CB]PrivateKeyEntry\f[R] for the signer that already exists in the
+keystore.
+This option is used to sign the certificate with the signer???s private
+key.
+This is especially useful for key agreement algorithms (i.e.
+the \f[CB]\-keyalg\f[R] value is \f[CB]XDH\f[R], \f[CB]X25519\f[R],
+\f[CB]X448\f[R], or \f[CB]DH\f[R]) as these keys cannot be used for digital
+signatures, and therefore a self\-signed certificate cannot be created.
+.PP
+The \f[CB]\-signerkeypass\f[R] value specifies the password of the
+signer???s private key.
+It can be specified if the private key of the signer entry is protected
+by a password different from the store password.
+.PP
 The \f[CB]\-dname\f[R] value specifies the X.500 Distinguished Name to be
-associated with the value of \f[CB]\-alias\f[R], and is used as the issuer
-and subject fields in the self\-signed certificate.
+associated with the value of \f[CB]\-alias\f[R].
+If the \f[CB]\-signer\f[R] option is not specified, the issuer and subject
+fields of the self\-signed certificate are populated with the specified
+distinguished name.
+If the \f[CB]\-signer\f[R] option is specified, the subject field of the
+certificate is populated with the specified distinguished name and the
+issuer field is populated with the subject field of the signer\[aq]s
+certificate.
 If a distinguished name is not provided at the command line, then the
 user is prompted for one.
 .PP
@@ -1531,9 +1561,9 @@ The following examples show the defaults for various option values:
 \-alias\ "mykey"
 
 \-keysize
-\ \ \ \ 2048\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "RSA",\ "DSA",\ or\ "RSASSA\-PSS")
+\ \ \ \ 2048\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "RSA",\ "DSA",\ "RSASSA\-PSS",\ or\ "DH")
 \ \ \ \ 256\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "EC")
-\ \ \ \ 255\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "EdDSA")
+\ \ \ \ 255\ (when\ using\ \-genkeypair\ and\ \-keyalg\ is\ "EdDSA",\ or\ "XDH)
 \ \ \ \ 56\ (when\ using\ \-genseckey\ and\ \-keyalg\ is\ "DES")
 \ \ \ \ 168\ (when\ using\ \-genseckey\ and\ \-keyalg\ is\ "DESede")
 
@@ -2531,16 +2561,17 @@ The first certificate in the chain contains the public key that
 corresponds to the private key.
 .RS
 .PP
-When keys are first generated, the chain starts off containing a single
-element, a self\-signed certificate.
+When keys are first generated, the chain usually starts off containing a
+single element, a self\-signed certificate.
 See \-genkeypair in \f[B]Commands\f[R].
 A self\-signed certificate is one for which the issuer (signer) is the
 same as the subject.
 The subject is the entity whose public key is being authenticated by the
 certificate.
-Whenever the \f[CB]\-genkeypair\f[R] command is called to generate a new
+When the \f[CB]\-genkeypair\f[R] command is called to generate a new
 public/private key pair, it also wraps the public key into a
-self\-signed certificate.
+self\-signed certificate (unless the \f[CB]\-signer\f[R] option is
+specified).
 .PP
 Later, after a Certificate Signing Request (CSR) was generated with the
 \f[CB]\-certreq\f[R] command and sent to a Certification Authority (CA),