6837214: Update JDK7 man pages

Reviewed-by: darcy, bpatel, tbell
Contributed-by: jacob.royal@sun.com

1 files changed, 570 insertions, 47 deletions

diff --git a/src/solaris/doc/sun/man/man1/keytool.1 b/src/solaris/doc/sun/man/man1/keytool.1
index da0a854153..12acb2a3c9 100644
--- a/src/solaris/doc/sun/man/man1/keytool.1
+++ b/src/solaris/doc/sun/man/man1/keytool.1
@@ -1,5 +1,4 @@
-.'" t
-." Copyright 2006 Sun Microsystems, Inc.  All Rights Reserved.
+." Copyright 2002-2006 Sun Microsystems, Inc.  All Rights Reserved.
 ." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 ."
 ." This code is free software; you can redistribute it and/or modify it
@@ -19,12 +18,12 @@
 ." Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 ." CA 95054 USA or visit www.sun.com if you need additional information or
 ." have any questions.
-." ` 
-.TH keytool 1 "07 Aug 2006"
-." Generated by html2man
+."
+.TH keytool 1 "04 May 2009"
+." Generated from HTML by html2man (author: Eric Armstrong)
 
 .LP
-.SH NAME
+.SH "Name"
 keytool \- Key and Certificate Management Tool
 .LP
 .RS 3
@@ -163,17 +162,19 @@ Below are the defaults for various option values.
 .fl
 
 .fl
-\-keystore \fP\f4the file named \fP\f4.keystore\fP\f3 in the user's home directory\fP\f3
+\-keystore the file named \fP\f4.keystore\fP\f3 in the user's home directory
 .fl
 
 .fl
-\-storetype \fP\f4the value of the "keystore.type" property in the security properties file,
+\-storetype the value of the "keystore.type" property in the security properties file,
+.fl
+           which is returned by the static \fP\f4getDefaultType\fP\f3 method in 
 .fl
-           which is returned by the static \fP\f4getDefaultType\fP\f3 method in \fP\f4java.security.KeyStore\fP\f3
+           \fP\f4java.security.KeyStore\fP\f3
 .fl
 
 .fl
-\-file \fP\f4stdin if reading, stdout if writing\fP\f3
+\-file stdin if reading, stdout if writing
 .fl
 
 .fl
@@ -185,7 +186,7 @@ Below are the defaults for various option values.
 .fi
 
 .LP
-In generating a public/private key pair, the signature algorithm (\f2\-sigalg\fP option) is derived from the algorithm of the underlying private key: If the underlying private key is of type "DSA", the \f2\-sigalg\fP option defaults to "SHA1withDSA", and if the underlying private key is of type "RSA", \f2\-sigalg\fP defaults to "MD5withRSA". Please consult the 
+In generating a public/private key pair, the signature algorithm (\f2\-sigalg\fP option) is derived from the algorithm of the underlying private key: If the underlying private key is of type "DSA", the \f2\-sigalg\fP option defaults to "SHA1withDSA", and if the underlying private key is of type "RSA", \f2\-sigalg\fP defaults to "SHA1withRSA". Please consult the 
 .na
 \f2Java Cryptography Architecture API Specification & Reference\fP @
 .fi
@@ -197,7 +198,7 @@ Common Options
 .RS 3
 
 .LP
-The \f2\-v\fP option can appear for all commands except \f2\-help\fP. If it appears, it signifies "verbose" mode; more information will be output. 
+The \f2\-v\fP option can appear for all commands except \f2\-help\fP. If it appears, it signifies "verbose" mode; more information will be provided in the output. 
 .LP
 There is also a \f2\-J\fP\f2javaoption\fP option that may appear for any command. If it appears, the specified \f2javaoption\fP string is passed through directly to the Java interpreter. This option should not contain any spaces. It is useful for adjusting the execution environment or memory usage. For a list of possible interpreter options, type \f2java \-h\fP or \f2java \-X\fP at the command line.
 .LP
@@ -234,9 +235,437 @@ Used in conjunction with \f2\-providerClass\fP. Represents an optional string in
 .TP 3
 \-protected 
 Either \f2true\fP or \f2false\fP. This value should be specified as \f2true\fP if a password must be given via a protected authentication path such as a dedicated PIN reader. 
-.RE
+.LP
+Note: Since there are two keystores involved in \f2\-importkeystore\fP command, two options, namely, \f2\-srcprotected\fP and \f2\-destprotected\fP are provided for the source keystore and the destination keystore respectively.  
+.TP 3
+\-ext {name{:critical}{=value}} 
+Denotes an X.509 certificate extension. The option can be used in \f2\-genkeypair\fP and \f2\-gencert\fP to embed extensions into the certificate generated, or in \f2\-certreq\fP to show what extensions are requested in the certificate request. The option can appear multiple times. name can be a supported extension name (see below) or an arbitrary OID number. value, if provided, denotes the parameter for the extension; if omitted, denotes the default value (if defined) of the extension or the extension requires no parameter. The \f2":critical"\fP modifier, if provided, means the extension's isCritical attribute is true; otherwise, false. 
+.RS 3
 
 .LP
+.LP
+Currently keytool supports these named extensions (case\-insensitive):
+.LP
+.LP
+.TS
+.if \n+(b.=1 .nr d. \n(.c-\n(c.-1
+.de 35
+.ps \n(.s
+.vs \n(.vu
+.in \n(.iu
+.if \n(.u .fi
+.if \n(.j .ad
+.if \n(.j=0 .na
+..
+.nf
+.nr #~ 0
+.if n .nr #~ 0.6n
+.ds #d .d
+.if \(ts\n(.z\(ts\(ts .ds #d nl
+.fc
+.nr 33 \n(.s
+.rm 80 81
+.nr 34 \n(.lu
+.eo
+.am 81
+.br
+.di a+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+The full form: "ca:{true|false}[,pathlen:<len>]"; or, <len>, a shorthand for "ca:true,pathlen:<len>"; or omitted, means "ca:true"
+.br
+.di
+.nr a| \n(dn
+.nr a- \n(dl
+..
+.ec \
+.eo
+.am 81
+.br
+.di b+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+usage(,usage)*, usage can be one of digitalSignature, nonRepudiation (contentCommitment), keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly. Usage can be abbreviated with the first few letters (say, dig for digitalSignature) or in camel\-case style (say, dS for digitalSignature, cRLS for cRLSign), as long as no ambiguity is found. Usage is case\-insensitive.
+.br
+.di
+.nr b| \n(dn
+.nr b- \n(dl
+..
+.ec \
+.eo
+.am 81
+.br
+.di c+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+usage(,usage)*, usage can be one of anyExtendedKeyUsage, serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, OCSPSigning, or any OID string. Named usage can be abbreviated with the first few letters or in camel\-case style, as long as no ambiguity is found. Usage is case\-insensitive.
+.br
+.di
+.nr c| \n(dn
+.nr c- \n(dl
+..
+.ec \
+.eo
+.am 80
+.br
+.di d+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(80 .ll \n(80u
+.in 0
+SAN or SubjectAlternativeName
+.br
+.di
+.nr d| \n(dn
+.nr d- \n(dl
+..
+.ec \
+.eo
+.am 81
+.br
+.di e+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+type:value(,type:value)*, type can be EMAIL, URI, DNS, IP, or OID, value is the string format value for the type.
+.br
+.di
+.nr e| \n(dn
+.nr e- \n(dl
+..
+.ec \
+.eo
+.am 80
+.br
+.di f+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(80 .ll \n(80u
+.in 0
+IAN or IssuerAlternativeName
+.br
+.di
+.nr f| \n(dn
+.nr f- \n(dl
+..
+.ec \
+.eo
+.am 81
+.br
+.di g+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+same as SubjectAlternativeName
+.br
+.di
+.nr g| \n(dn
+.nr g- \n(dl
+..
+.ec \
+.eo
+.am 81
+.br
+.di h+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+method:location\-type:location\-value (,method:location\-type:location\-value)*, method can be "timeStamping", "caRepository" or any OID. location\-type and location\-value can be any type:value supported by the SubjectAlternativeName extension.
+.br
+.di
+.nr h| \n(dn
+.nr h- \n(dl
+..
+.ec \
+.eo
+.am 80
+.br
+.di i+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(80 .ll \n(80u
+.in 0
+AIA or AuthorityInfoAccess
+.br
+.di
+.nr i| \n(dn
+.nr i- \n(dl
+..
+.ec \
+.eo
+.am 81
+.br
+.di j+
+.35
+.ft \n(.f
+.ll \n(34u*1u/3u
+.if \n(.l<\n(81 .ll \n(81u
+.in 0
+same as SubjectInfoAccess. method can be "ocsp","caIssuers" or any OID.
+.br
+.di
+.nr j| \n(dn
+.nr j- \n(dl
+..
+.ec \
+.35
+.nf
+.ll \n(34u
+.nr 80 0
+.nr 38 \w\f3Name\fP
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 38 \wBC or BasicConstraints
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 38 \wKU or KeyUsage
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 38 \wEKU or ExtendedkeyUsage
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 38 \wSIA or SubjectInfoAccess
+.if \n(80<\n(38 .nr 80 \n(38
+.80
+.rm 80
+.nr 38 \n(d-
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 38 \n(f-
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 38 \n(i-
+.if \n(80<\n(38 .nr 80 \n(38
+.nr 81 0
+.nr 38 \w\f3Value\fP
+.if \n(81<\n(38 .nr 81 \n(38
+.81
+.rm 81
+.nr 38 \n(a-
+.if \n(81<\n(38 .nr 81 \n(38
+.nr 38 \n(b-
+.if \n(81<\n(38 .nr 81 \n(38
+.nr 38 \n(c-
+.if \n(81<\n(38 .nr 81 \n(38
+.nr 38 \n(e-
+.if \n(81<\n(38 .nr 81 \n(38
+.nr 38 \n(g-
+.if \n(81<\n(38 .nr 81 \n(38
+.nr 38 \n(h-
+.if \n(81<\n(38 .nr 81 \n(38
+.nr 38 \n(j-
+.if \n(81<\n(38 .nr 81 \n(38
+.35
+.nf
+.ll \n(34u
+.nr 38 1n
+.nr 79 0
+.nr 40 \n(79+(0*\n(38)
+.nr 80 +\n(40
+.nr 41 \n(80+(3*\n(38)
+.nr 81 +\n(41
+.nr TW \n(81
+.if t .if \n(TW>\n(.li .tm Table at line 288 file Input is too wide - \n(TW units
+.fc  
+.nr #T 0-1
+.nr #a 0-1
+.eo
+.de T#
+.ds #d .d
+.if \(ts\n(.z\(ts\(ts .ds #d nl
+.mk ##
+.nr ## -1v
+.ls 1
+.ls
+..
+.ec
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'\f3Name\fP\h'|\n(41u'\f3Value\fP
+.ne \n(a|u+\n(.Vu
+.if (\n(a|+\n(#^-1v)>\n(#- .nr #- +(\n(a|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'BC or BasicConstraints\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.a+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.ne \n(b|u+\n(.Vu
+.if (\n(b|+\n(#^-1v)>\n(#- .nr #- +(\n(b|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'KU or KeyUsage\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.b+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.ne \n(c|u+\n(.Vu
+.if (\n(c|+\n(#^-1v)>\n(#- .nr #- +(\n(c|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'EKU or ExtendedkeyUsage\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.c+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.ne \n(d|u+\n(.Vu
+.ne \n(e|u+\n(.Vu
+.if (\n(d|+\n(#^-1v)>\n(#- .nr #- +(\n(d|+\n(#^-\n(#--1v)
+.if (\n(e|+\n(#^-1v)>\n(#- .nr #- +(\n(e|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(40u
+.in +\n(37u
+.d+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.e+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.ne \n(f|u+\n(.Vu
+.ne \n(g|u+\n(.Vu
+.if (\n(f|+\n(#^-1v)>\n(#- .nr #- +(\n(f|+\n(#^-\n(#--1v)
+.if (\n(g|+\n(#^-1v)>\n(#- .nr #- +(\n(g|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(40u
+.in +\n(37u
+.f+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.g+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.ne \n(h|u+\n(.Vu
+.if (\n(h|+\n(#^-1v)>\n(#- .nr #- +(\n(h|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'SIA or SubjectInfoAccess\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.h+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.ne \n(i|u+\n(.Vu
+.ne \n(j|u+\n(.Vu
+.if (\n(i|+\n(#^-1v)>\n(#- .nr #- +(\n(i|+\n(#^-\n(#--1v)
+.if (\n(j|+\n(#^-1v)>\n(#- .nr #- +(\n(j|+\n(#^-\n(#--1v)
+.ta \n(80u \n(81u 
+.nr 31 \n(.f
+.nr 35 1m
+\&\h'|\n(40u'\h'|\n(41u'
+.mk ##
+.nr 31 \n(##
+.sp |\n(##u-1v
+.nr 37 \n(40u
+.in +\n(37u
+.i+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(##u-1v
+.nr 37 \n(41u
+.in +\n(37u
+.j+
+.in -\n(37u
+.mk 32
+.if \n(32>\n(31 .nr 31 \n(32
+.sp |\n(31u
+.fc
+.nr T. 1
+.T# 1
+.35
+.rm a+
+.rm b+
+.rm c+
+.rm d+
+.rm e+
+.rm f+
+.rm g+
+.rm h+
+.rm i+
+.rm j+
+.TE
+.if \n-(b.=0 .nr c. \n(.c-\n(d.-38
+
+.LP
+.LP
+For name as OID, value is the HEX dumped DER encoding of the extnValue for the extension excluding the OCTET STRING type and length bytes. Any extra character other than standard HEX numbers (0\-9, a\-f, A\-F) are ignored in the HEX string. Therefore, both \f2"01:02:03:04"\fP and \f2"01020304"\fP are accepted as identical values. If there's no value, the extension has an empty value field then.
+.LP
+.LP
+A special name \f2"honored"\fP, used in \-gencert only, denotes how the extensions included in the certificate request should be honored. The value for this name is a comma\-seperated list of \f2"all"\fP (all requested extensions are honored), \f2"name{:[critical|non\-critical]}"\fP (the named extension is honored, but using a different isCritical attribute) and \f2"\-name"\fP (used with all, denotes an exception). Requested extensions are not honored by default.
+.LP
+.LP
+If, besides the \-ext honored option, another named or OID \-ext option is provided, this extension will be added to those already honored. However, if this name (or OID) also appears in the honored value, its value and criticality overrides the one in the request.
+.LP
+.LP
+The subjectKeyIdentifier extension is always created. For non self\-signed certificates, the authorityKeyIdentifier is always created.
+.LP
+.RE
+.RE
 .RE
 .SH "COMMANDS"
 .LP
@@ -250,7 +679,15 @@ Creating or Adding Data to the Keystore
 .LP
 .RS 3
 .TP 3
-\-genkeypair {\-alias alias} {\-keyalg keyalg} {\-keysize keysize} {\-sigalg sigalg} [\-dname dname] [\-keypass keypass] {\-validity valDays} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption} 
+\-gencert {\-infile infile} {\-outfile outfile} {\-ext ext}* {\-rfc} {\-alias alias} {\-sigalg sigalg} {\-validity valDays} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] [\-keypass keypass] {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption} 
+.LP
+Generates a certificate as a response to a certificate request file (which can be created by the \f2keytool \-certreq\fP command). The command reads the request from infile (if omitted, from the standard input), signs it using alias's private key, and output the X.509 certificate into outfile (if omitted, to the standard output). If \f2\-rfc\fP is specified, output format is BASE64\-encoded PEM; otherwise, a binary DER is created. 
+.LP
+\f2sigalg\fP specifies the algorithm that should be used to sign the certificate. valDays tells the number of days for which the certificate should be considered valid. 
+.LP
+\f2ext\fP shows what X.509 extensions will be embedded in the certificate. Read Common Options for the grammar of \f2\-ext\fP.  
+.TP 3
+\-genkeypair {\-alias alias} {\-keyalg keyalg} {\-keysize keysize} {\-sigalg sigalg} [\-dname dname] [\-keypass keypass] {\-startdate value} {\-validity valDays} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption} 
 .LP
 Generates a key pair (a public key and associated private key). Wraps the public key into 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 identified by \f2alias\fP. 
 .LP
@@ -260,9 +697,60 @@ Generates a key pair (a public key and associated private key). Wraps the public
 .LP
 \f2keypass\fP is a password used to protect the private key of the generated key pair. If no password is provided, the user is prompted for it. If you press RETURN at the prompt, the key password is set to the same password as that used for the keystore. \f2keypass\fP must be at least 6 characters long. 
 .LP
-\f2valDays\fP tells the number of days for which the certificate should be considered valid. 
+\f2startdate\fP specifies the issue time of the certificate, also known as the "Not Before" value of the X.509 certificate's Validity field. 
+.RS 3
+
+.LP
+.LP
+The option value can be set in one of these two forms:
+.LP
+.RS 3
+.TP 3
+1.
+.LP
+([+\-]\f2nnn\fP[ymdHMS])+  
+.TP 3
+2.
+.LP
+[yyyy/mm/dd] [HH:MM:SS]  
+.RE
+
+.LP
+.LP
+With the first form, the issue time is shifted by the specified value from the current time. The value is a concatenation of a sequence of sub values. Inside each sub value, the plus sign ("+") means shifting forward, and the minus sign ("\-") means shifting backward. The time to be shifted is \f2nnn\fP units of years, months, days, hours, minutes, or seconds (denoted by a single character of "y", "m", "d", "H", "M", or "S" respectively). The exact value of the issue time is calculated using the \f2java.util.GregorianCalendar.add(int field, int amount)\fP method on each sub value, from left to right. For example, by specifying \f2"\-startdate \-1y+1m\-1d"\fP, the issue time will be:
+.LP
+.RS 3
+
+.LP
+.nf
+\f3
+.fl
+   Calendar c = new GregorianCalendar();
+.fl
+   c.add(Calendar.YEAR, \-1);
+.fl
+   c.add(Calendar.MONTH, 1);
+.fl
+   c.add(Calendar.DATE, \-1);
+.fl
+   return c.getTime()
+.fl
+\fP
+.fi
+.RE
+
+.LP
+.LP
+With the second form, the user sets the exact issue time in two parts, year/month/day and hour:minute:second (using the local timezone). The user may provide only one part, which means the other part is the same as the current date (or time). User must provide the exact number of digits as shown in the format definition (padding with 0 if shorter). When both the date and time are provided, there is one (and only one) space character between the two parts. The hour should always be provided in 24 hour format.
+.LP
 .LP
-This command was named \f2\-genkey\fP in previous releases. This old name is still supported in this release and will be supported in future releases, but for clarify the new name, \f2\-genkeypair\fP, is preferred going forward.  
+When the option is not provided, the start date is the current time. The option can be provided at most once.
+.LP
+.RE
+.LP
+\f2valDays\fP specifies the number of days (starting at the date specified by \f2\-startdate\fP, or the current date if \f2\-startdate\fP is not specified) for which the certificate should be considered valid. 
+.LP
+This command was named \f2\-genkey\fP in previous releases. This old name is still supported in this release and will be supported in future releases, but for clarity the new name, \f2\-genkeypair\fP, is preferred going forward.  
 .TP 3
 \-genseckey {\-alias alias} {\-keyalg keyalg} {\-keysize keysize} [\-keypass keypass] {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption} 
 .LP
@@ -272,7 +760,7 @@ Generates a secret key and stores it in a new \f2KeyStore.SecretKeyEntry\fP iden
 .TP 3
 \-importcert {\-alias alias} {\-file cert_file} [\-keypass keypass] {\-noprompt} {\-trustcacerts} {\-storetype storetype} {\-keystore keystore} [\-storepass storepass] {\-providerName provider_name} {\-providerClass provider_class_name {\-providerArg provider_arg}} {\-v} {\-protected} {\-Jjavaoption} 
 .LP
-Reads the certificate or certificate chain (where the latter is supplied in a PKCS#7 formatted reply) from the file \f2cert_file\fP, and stores it in the keystore entry identified by \f2alias\fP. If no file is given, the certificate or PKCS#7 reply is read from stdin. 
+Reads the certificate or certificate chain (where the latter is supplied in a PKCS#7 formatted reply or a sequence of X.509 certificates) from the file \f2cert_file\fP, and stores it in the keystore entry identified by \f2alias\fP. If no file is given, the certificate or certificate chain is read from stdin. 
 .LP
 \f3keytool\fP can import X.509 v1, v2, and v3 certificates, and PKCS#7 formatted certificate chains consisting of certificates of that type. The data to be imported must be provided either in binary encoding format, or in printable encoding format (also known as Base64 encoding) as defined by the Internet RFC 1421 standard. In the latter case, the encoding must be bounded at the beginning by a string that starts with "\-\-\-\-\-BEGIN", and bounded at the end by a string that starts with "\-\-\-\-\-END". 
 .LP
@@ -297,8 +785,6 @@ Which type of import is intended is indicated by the value of the \f2\-alias\fP
 .RE
 \f3Importing a New Trusted Certificate\fP 
 .RS 3
-
-.LP
 .LP
 Before adding the certificate to the keystore, \f3keytool\fP tries to verify it by attempting to construct a chain of trust from that certificate to a self\-signed certificate (belonging to a root CA), using trusted certificates that are already available in the keystore.
 .LP
@@ -323,7 +809,7 @@ o
 \f3If the reply is a single X.509 certificate\fP, \f3keytool\fP attempts to establish a trust chain, starting at the certificate reply and ending at a self\-signed certificate (belonging to a root CA). The certificate reply and the hierarchy of certificates used to authenticate the certificate reply form the new certificate chain of \f2alias\fP. If a trust chain cannot be established, the certificate reply is not imported. In this case, \f3keytool\fP does not print out the certificate and prompt the user to verify it, because it is very hard (if not impossible) for a user to determine the authenticity of the certificate reply. 
 .TP 2
 o
-\f3If the reply is a PKCS#7 formatted certificate chain\fP, the chain is first ordered (with the user certificate first and the self\-signed root CA certificate last), before \f3keytool\fP attempts to match the root CA certificate provided in the reply with any of the trusted certificates in the keystore or the "cacerts" keystore file (if the \f2\-trustcacerts\fP option was specified). If no match can be found, the information of the root CA certificate is printed out, and the user is prompted to verify it, e.g., by comparing the displayed certificate fingerprints with the fingerprints obtained from some other (trusted) source of information, which might be the root CA itself. The user then has the option of aborting the import operation. If the \f2\-noprompt\fP option is given, however, there will be no interaction with the user. 
+\f3If the reply is a PKCS#7 formatted certificate chain or a sequence of X.509 certificates\fP, the chain is ordered with the user certificate first followed by zero or more CA certificates. If the chain ends with a self\-signed root CA certificate and \f2\-trustcacerts\fP option was specified, \f3keytool\fP will attempt to match it with any of the trusted certificates in the keystore or the "cacerts" keystore file. If the chain does not end with a self\-signed root CA certificate and the \f2\-trustcacerts\fP option was specified, \f3keytool\fP will try to find one from the trusted certificates in the keystore or the "cacerts" keystore file and add it to the end of the chain. If the certificate is not found and \f2\-noprompt\fP option is not specified, the information of the last certificate in the chain is printed out, and the user is prompted to verify it. 
 .RE
 
 .LP
@@ -345,6 +831,10 @@ If the \f2srcalias\fP option is not provided, then all entries in the source key
 If the destination alias already exists in the destination keystore, the user is prompted to either overwrite the entry, or to create a new entry under a different alias name. 
 .LP
 Note that if \f2\-noprompt\fP is provided, the user will not be prompted for a new destination alias. Existing entries will automatically be overwritten with the destination alias name. Finally, entries that can not be imported are automatically skipped and a warning is output.  
+.TP 3
+\-printcertreq {\-file file} 
+.LP
+Prints the content of a PKCS #10 format certificate request, which can be generated by the keytool \-certreq command. The command reads the request from file; if omitted, from the standard input.  
 .RE
 .RE
 .SS 
@@ -396,16 +886,20 @@ Displaying Data
 .LP
 Prints (to stdout) the contents of the keystore entry identified by \f2alias\fP. If no alias is specified, the contents of the entire keystore are printed. 
 .LP
-This command by default prints the MD5 fingerprint of a certificate. If the \f2\-v\fP option is specified, the certificate is printed in human\-readable format, with additional information such as the owner, issuer, serial number, and any extensions. If the \f2\-rfc\fP option is specified, certificate contents are printed using the printable encoding format, as defined by the Internet RFC 1421 standard 
+This command by default prints the SHA1 fingerprint of a certificate. If the \f2\-v\fP option is specified, the certificate is printed in human\-readable format, with additional information such as the owner, issuer, serial number, and any extensions. If the \f2\-rfc\fP option is specified, certificate contents are printed using the printable encoding format, as defined by the Internet RFC 1421 standard 
 .LP
 You cannot specify both \f2\-v\fP and \f2\-rfc\fP.  
 .TP 3
-\-printcert {\-file cert_file} {\-v} {\-Jjavaoption} 
+\-printcert {\-file cert_file | \-sslserver host[:port]} {\-rfc} {\-v} {\-Jjavaoption} 
+.LP
 .LP
+If \f2\-rfc\fP is specified, keytool prints the certificate in PEM mode as defined by the Internet RFC 1421 standard. 
 .LP
-Internet RFC 1421 standard. 
+If the certificate is read from a file or stdin, it may be either binary encoded or in printable encoding format, as defined by the Internet RFC 1421 standard 
 .LP
-Note: This option can be used independently of a keystore.  
+If the SSL server is behind a firewall, \f2\-J\-Dhttps.proxyHost=proxyhost\fP and \f2\-J\-Dhttps.proxyPort=proxyport\fP can be specified on the command line for proxy tunneling. See the JSSE Reference Guide for more information. 
+.LP
+\f3Note\fP: This option can be used independently of a keystore.  
 .RE
 
 .LP
@@ -604,11 +1098,7 @@ Exporting a Certificate Authenticating Your Public Key
 .RS 3
 
 .LP
-Suppose you have used the 
-.na
-\f2jarsigner\fP @
-.fi
-http://java.sun.com/javase/6/docs/tooldocs/solaris/jarsigner.html tool to sign a Java ARchive (JAR) file. Clients that want to use the file will want to authenticate your signature. 
+Suppose you have used the jarsigner(1) tool to sign a Java ARchive (JAR) file. Clients that want to use the file will want to authenticate your signature. 
 .LP
 One way they can do this is by first importing your public key certificate into their keystore as a "trusted" entry. You can export the certificate and supply it to your clients. As an example, you can copy your certificate to a file named \f2MJ.cer\fP via the following, assuming the entry is aliased by "mykey":
 .LP
@@ -675,6 +1165,45 @@ keytool \-importkeystore
 .RE
 
 .LP
+.SS 
+Generating Certificates for a typical SSL Server
+.LP
+.RS 3
+
+.LP
+.LP
+Keytool commands to generate keypairs and certificates for three entities, namely, Root CA (root), Intermadiate CA (ca), and SSL server (server) are as follows:
+.LP
+.nf
+\f3
+.fl
+keytool \-keystore root.jks \-genkeypair \-alias root \-ext bc:c
+.fl
+keytool \-keystore ca.jks \-alias ca
+.fl
+keytool \-keystore server.jks \-alias server
+.fl
+ 
+.fl
+keytool \-keystore root.jks \-alias root \-exportcert > root.pem
+.fl
+ 
+.fl
+keytool \-keystore ca.jks \-certreq \-alias ca | keytool \-keystore root.jks \-gencert \-alias root \-ext BC=0 > ca.pem
+.fl
+keytool \-keystore ca.jks \-importcert \-alias ca \-file ca.pem
+.fl
+ 
+.fl
+keytool \-keystore server.jks \-certreq \-alias server | keytool \-keystore ca.jks \-gencert \-alias ca \-ext ku:c=dig,kE >server.pem 
+.fl
+cat root.pem ca.pem server.pem | keytool \-keystore server.jks \-importcert \-alias server
+.fl
+\fP
+.fi
+.RE
+
+.LP
 .SH "TERMINOLOGY and WARNINGS"
 .LP
 
@@ -757,7 +1286,11 @@ Currently, two command\-line tools (\f3keytool\fP and \f3jarsigner\fP) and a GUI
 There is a built\-in default implementation, provided by Sun Microsystems. It implements the keystore as a file, utilizing a proprietary keystore type (format) named "JKS". It protects each private key with its individual password, and also protects the integrity of the entire keystore with a (possibly different) password.
 .LP
 .LP
-Keystore implementations are provider\-based. More specifically, the application interfaces supplied by \f2KeyStore\fP are implemented in terms of a "Service Provider Interface" (SPI). That is, there is a corresponding abstract \f2KeystoreSpi\fP class, also in the \f2java.security\fP package, which defines the Service Provider Interface methods that "providers" must implement. (The term "provider" refers to a package or a set of packages that supply a concrete implementation of a subset of services that can be accessed by the Java Security API.) Thus, to provide a keystore implementation, clients must implement a "provider" and supply a KeystoreSpi subclass implementation, as described in How to Implement a Provider for the Java Cryptography Architecture.
+Keystore implementations are provider\-based. More specifically, the application interfaces supplied by \f2KeyStore\fP are implemented in terms of a "Service Provider Interface" (SPI). That is, there is a corresponding abstract \f2KeystoreSpi\fP class, also in the \f2java.security\fP package, which defines the Service Provider Interface methods that "providers" must implement. (The term "provider" refers to a package or a set of packages that supply a concrete implementation of a subset of services that can be accessed by the Java Security API.) Thus, to provide a keystore implementation, clients must implement a "provider" and supply a KeystoreSpi subclass implementation, as described in 
+.na
+\f2How to Implement a Provider for the Java Cryptography Architecture\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html.
 .LP
 .LP
 Applications can choose different \f2types\fP of keystore implementations from different providers, using the "getInstance" factory method supplied in the \f2KeyStore\fP class. A keystore type defines the storage and data format of the keystore information, and the algorithms used to protect private/secret keys in the keystore and the integrity of the keystore itself. Keystore implementations of different types are not compatible.
@@ -1130,13 +1663,6 @@ OU="GTE CyberTrust Solutions, Inc.", O=GTE Corporation, C=US
 OU=CyberTrust, O=Baltimore, C=IE 
 .TP 2
 *
-\f3Alias\fP: gtecybertrustca
-.br
-\f3Owner DN\fP: CN=GTE CyberTrust Root,
-.br
-O=GTE Corporation, C=US 
-.TP 2
-*
 \f3Alias\fP: gtecybertrust5ca
 .br
 \f3Owner DN\fP: CN=GTE CyberTrust Root 5,
@@ -1368,7 +1894,7 @@ Certificates read by the \f2\-importcert\fP and \f2\-printcert\fP commands can b
 The \f2\-exportcert\fP command by default outputs a certificate in binary encoding, but will instead output a certificate in the printable encoding format, if the \f2\-rfc\fP option is specified.
 .LP
 .LP
-The \f2\-list\fP command by default prints the MD5 fingerprint of a certificate. If the \f2\-v\fP option is specified, the certificate is printed in human\-readable format, while if the \f2\-rfc\fP option is specified, the certificate is output in the printable encoding format.
+The \f2\-list\fP command by default prints the SHA1 fingerprint of a certificate. If the \f2\-v\fP option is specified, the certificate is printed in human\-readable format, while if the \f2\-rfc\fP option is specified, the certificate is output in the printable encoding format.
 .LP
 .LP
 In its printable encoding format, the encoded certificate is bounded at the beginning by
@@ -1575,18 +2101,15 @@ If you don't specify a required password option on a command line, you will be p
 .RS 3
 .TP 2
 o
-.na
-\f2jar\fP @
-.fi
-http://java.sun.com/javase/6/docs/tooldocs/solaris/jar.html tool documentation 
+.LP
+jar(1) tool documentation  
 .TP 2
 o
-.na
-\f2jarsigner\fP @
-.fi
-http://java.sun.com/javase/6/docs/tooldocs/solaris/jarsigner.html tool documentation 
+.LP
+jarsigner(1) tool documentation  
 .TP 2
 o
+.LP
 the 
 .na
 \f4Security\fP @
@@ -1595,7 +2118,7 @@ http://java.sun.com/docs/books/tutorial/security/index.html trail of the
 .na
 \f4Java Tutorial\fP @
 .fi
-http://java.sun.com/docs/books/tutorial/trailmap.html for examples of the use of \f3keytool\fP 
+http://java.sun.com/docs/books/tutorial for examples of the use of \f3keytool\fP  
 .RE
 
 .LP