Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GKEYTOOL(1)			      GNU			   GKEYTOOL(1)

NAME
       gkeytool	- Manage private keys and public certificates

SYNOPSIS
       keytool [COMMAND] ...

DESCRIPTION
       Cryptographic credentials, in a Java environment, are usually stored in
       a Key Store. The	Java SDK specifies a Key Store as a persistent
       container of two	types of objects: Key Entries and Trusted
       Certificates. The security tool keytool is a Java-based application for
       managing	those types of objects.

       A Key Entry represents the private key part of a	key-pair used in
       Public-Key Cryptography,	and a signed X.509 certificate which
       authenticates the public	key part for a known entity; i.e. the owner of
       the key-pair. The X.509 certificate itself contains the public key part
       of the key-pair.

       A Trusted Certificate is	a signed X.509 certificate issued by a trusted
       entity. The Trust in this context is relative to	the User of the
       keytool.	In other words,	the existence of a Trusted Certificate in the
       Key Store processed by a	keytool	command	implies	that the User trusts
       the Issuer of that Trusted Certificate to also sign, and	hence
       authenticates, other Subjects the tool may process.

       Trusted Certificates are	important because they allow the tool to
       mechanically construct Chains of	Trust starting from one	of the Trusted
       Certificates in a Key Store and ending with a certificate whose Issuer
       is potentially unknown. A valid chain is	an ordered list, starting with
       a Trusted Certificate (also called the anchor), ending with the target
       certificate, and	satisfying the condition that the Subject of
       certificate "#i"	is the Issuer of certificate "#i + 1".

       The keytool is invoked from the command line as follows:

	       keytool [COMMAND] ...

       Multiple	COMMANDs may be	specified at once, each	complete with its own
       options.	keytool	will parse all the arguments, before processing, and
       executing, each "COMMAND". If an	exception occurs while executing one
       COMMAND keytool will abort. Note	however	that because the
       implementation of the tool uses code to parse command line options that
       also supports GNU-style options,	you have to separate each command
       group with a double-hyphen; e.g

	       keytool -list --	-printcert -alias mykey

OPTIONS
       - Add/Update commands
	   -genkey [OPTION]...
	       Generate	a new Key Entry, eventually creating a new key store.

	   -import [OPTION]...
	       Add, to a key store, Key	Entries	(private keys and certificate
	       chains authenticating the public	keys) and Trusted Certificates
	       (3rd party certificates which can be used as Trust Anchors when
	       building	chains-of-trust).

	   -selfcert [OPTION]...
	       Generate	a new self-signed Trusted Certificate.

	   -cacert [OPTION]...
	       Import a	CA Trusted Certificate.

	   -identitydb [OPTION]...
	       NOT IMPLEMENTED YET.Import a JDK	1.1 style Identity Database.

       - Export	commands
	   -certreq [OPTION]...
	       Issue a Certificate Signing Request (CSR) which can be then
	       sent to a Certification Authority (CA) to issue a certificate
	       signed (by the CA) and authenticating the Subject of the
	       request.

	   -export [OPTION]...
	       Export a	certificate from a key store.

       - Display commands
	   -list [OPTION]...
	       Print one or all	certificates in	a key store to "STDOUT".

	   -printcert [OPTION]...
	       Print a human-readable form of a	certificate, in	a designated
	       file, to	"STDOUT".

       - Management commands
	   -keyclone [OPTION]...
	       Clone a Key Entry in a key store.

	   -storepasswd	[OPTION]...
	       Change the password protecting a	key store.

	   -keypasswd [OPTION]...
	       Change the password protecting a	Key Entry in a key store.

	   -delete [OPTION]...
	       Delete a	Key Entry or a Trusted Certificate from	a key store.

       Common options

       The following OPTIONs are used in more than one COMMAND.	They are
       described here to reduce	redundancy.

       -alias Alias
	   Every entry,	be it a	Key Entry or a Trusted Certificate, in a key
	   store is uniquely identified	by a user-defined Alias	string.	Use
	   this	option to specify the Alias to use when	referring to an	entry
	   in the key store. Unless specified otherwise, a default value of
	   "mykey" shall be used when this option is omitted from the command
	   line.

       -keyalg ALGORITHM
	   Use this option to specify the canonical name of the	key-pair
	   generation algorithm. The default value for this option is "DSS" (a
	   synonym for the Digital Signature Algorithm also known as DSA).

       -keysize	SIZE
	   Use this option to specify the number of bits of the	shared modulus
	   (for	both the public	and private keys) to use when generating new
	   keys. A default value of 1024 will be used if this option is
	   omitted from	the command line.

       -validity DAY_COUNT
	   Use this option to specify the number of days a newly generated
	   certificate will be valid for. The default value is 90 (days) if
	   this	option is omitted from the command line.

       -storetype STORE_TYPE
	   Use this option to specify the type of the key store	to use.	The
	   default value, if this option is omitted, is	that of	the property
	   "keystore.type" in the security properties file, which is obtained
	   by invoking the static method call "getDefaultType()" in
	   "java.security.KeyStore".

       -storepass PASSWORD
	   Use this option to specify the password protecting the key store.
	   If this option is omitted from the command line, you	will be
	   prompted to provide a password.

       -keystore URL
	   Use this option to specify the location of the key store to use.
	   The default value is	a file URL referencing the file	named
	   .keystore located in	the path returned by the call to
	   "java.lang.System#getProperty(String)" using	"user.home" as
	   argument.

	   If a	URL was	specified, but was found to be malformed --e.g.
	   missing protocol element-- the tool will attempt to use the URL
	   value as a file-name	(with absolute or relative path-name) of a key
	   store --as if the protocol was "file:".

       -provider PROVIDER_CLASS_NAME
	   A fully qualified class name	of a Security Provider to add to the
	   current list	of Security Providers already installed	in the JVM in-
	   use.	If a provider class is specified with this option, and was
	   successfully	added to the runtime --i.e. it was not already
	   installed-- then the	tool will attempt to removed this Security
	   Provider before exiting.

       -file FILE
	   Use this option to designate	a file to use with a command. When
	   specified with this option, the value is expected to	be the fully
	   qualified path of a file accessible by the File System. Depending
	   on the command, the file may	be used	as input or as output. When
	   this	option is omitted from the command line, "STDIN" will be used
	   instead, as the source of input, and	"STDOUT" will be used instead
	   as the output destination.

       -v  Unless specified otherwise, use this	option to enable more verbose
	   output.

       Add/Update commands

       The -genkey command

       Use this	command	to generate a new key-pair (both private and public
       keys), and save these credentials in the	key store as a Key Entry,
       associated with the designated (if was specified	with the -alias
       option) or default (if the -alias option	is omitted) Alias.

       The private key material	will be	protected with a user-defined password
       (see -keypass option). The public key on	the other hand will be part of
       a self-signed X.509 certificate,	which will form	a 1-element chain and
       will be saved in	the key	store.

       -alias ALIAS
	   See Common Options for more details.

       -keyalg ALGORITHM
	   See Common Options for more details.

       -keysize	KEY_SIZE
	   See Common Options for more details.

       -sigalg ALGORITHM
	   The canonical name of the digital signature algorithm to use	for
	   signing certificates. If this option	is omitted, a default value
	   will	be chosen based	on the type of the key-pair; i.e., the
	   algorithm that ends up being	used by	the -keyalg option. If the
	   key-pair generation algorithm is "DSA", the value for the signature
	   algorithm will be "SHA1withDSA". If on the other hand the key-pair
	   generation algorithm	is "RSA", then the tool	will use "MD5withRSA"
	   as the signature algorithm.

       -dname NAME
	   This	a mandatory value for the command. If no value is specified
	   --i.e. the -dname option is omitted-- the tool will prompt you to
	   enter a Distinguished Name to use as	both the Owner and Issuer of
	   the generated self-signed certificate.

	   See Common Options for more details.

       -keypass	PASSWORD
	   Use this option to specify the password which the tool will use to
	   protect the newly created Key Entry.

	   If this option is omitted, you will be prompted to provide a
	   password.

       -validity DAY_COUNT
	   See Common Options for more details.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -import command

       Use this	command	to read	an X.509 certificate, or a PKCS#7 Certificate
       Reply from a designated input source and	incorporate the	certificates
       into the	key store.

       If the Alias does not already exist in the key store, the tool treats
       the certificate read from the input source as a new Trusted
       Certificate. It then attempts to	discover a chain-of-trust, starting
       from that certificate and ending	at another Trusted Certificate,
       already stored in the key store.	If the -trustcacerts option is
       present,	an additional key store, of type "JKS" named cacerts, and
       assumed to be present in	${JAVA_HOME}/lib/security will also be
       consulted if found --"${JAVA_HOME}" refers to the location of an
       installed Java Runtime Environment (JRE). If no chain-of-trust can be
       established, and	unless the "-noprompt" option has been specified, the
       certificate is printed to "STDOUT" and the user is prompted for a
       confirmation.

       If Alias	exists in the key store, the tool will treat the
       certificate(s) read from	the input source as a Certificate Reply, which
       can be a	chain of certificates, that eventually would replace the chain
       of certificates associated with the Key Entry of	that Alias. The
       substitution of the certificates	only occurs if a chain-of-trust	can be
       established between the bottom certificate of the chain read from the
       input file and the Trusted Certificates already present in the key
       store. Again, if	the -trustcacerts option is specified, additional
       Trusted Certificates in the same	cacerts	key store will be considered.
       If no chain-of-trust can	be established,	the operation will abort.

       -alias ALIAS
	   See Common Options for more details.

       -file FILE
	   See Common Options for more details.

       -keypass	PASSWORD
	   Use this option to specify the password which the tool will use to
	   protect the Key Entry associated with the designated	Alias, when
	   replacing this Alias' chain of certificates with that found in the
	   certificate reply.

	   If this option is omitted, and the chain-of-trust for the
	   certificate reply has been established, the tool will first attempt
	   to unlock the Key Entry using the same password protecting the key
	   store. If this fails, you will then be prompted to provide a
	   password.

       -noprompt
	   Use this option to prevent the tool from prompting the user.

       -trustcacerts
	   Use this option to indicate to the tool that	a key store, of	type
	   "JKS", named	cacerts, and usually located in	lib/security in	an
	   installed Java Runtime Environment should be	considered when	trying
	   to establish	chain-of-trusts.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -selfcert command

       Use this	command	to generate a self-signed X.509	version	1 certificate.
       The newly generated certificate will form a chain of one	element	which
       will replace the	previous chain associated with the designated Alias
       (if -alias option was specified), or the	default	Alias (if -alias
       option was omitted).

       -alias ALIAS
	   See Common Options for more details.

       -sigalg ALGORITHM
	   The canonical name of the digital signature algorithm to use	for
	   signing the certificate. If this option is omitted, a default value
	   will	be chosen based	on the type of the private key associated with
	   the designated Alias. If the	private	key is a "DSA" one, the	value
	   for the signature algorithm will be "SHA1withDSA". If on the	other
	   hand	the private key	is an "RSA" one, then the tool will use
	   "MD5withRSA"	as the signature algorithm.

       -dname NAME
	   Use this option to specify the Distinguished	Name of	the newly
	   generated self-signed certificate. If this option is	omitted, the
	   existing Distinguished Name of the base certificate in the chain
	   associated with the designated Alias	will be	used instead.

	   See Common Options for more details.

       -validity DAY_COUNT
	   See Common Options for more details.

       -keypass	PASSWORD
	   Use this option to specify the password which the tool will use to
	   unlock the Key Entry	associated with	the designated Alias.

	   If this option is omitted, the tool will first attempt to unlock
	   the Key Entry using the same	password protecting the	key store. If
	   this	fails, you will	then be	prompted to provide a password.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -cacert command

       Use this	command	to import, a CA	certificate and	add it to the key
       store as	a Trusted Certificate. The Alias for this new entry will be
       constructed from	the FILE's base-name after replacing hyphens and dots
       with underscores.

       This command is useful when used	in a script that recursively visits a
       directory of CA certificates to populate	a "cacerts.gkr"	Key Store of
       trusted certificates which can then be used commands that specify the
       -trustcacerts option.

       -file FILE
	   See Common Options for more details.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -identitydb command

       NOT IMPLEMENTED YET.

       Use this	command	to import a JDK	1.1 style Identity Database.

       -file FILE
	   See Common Options for more details.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       Export commands

       The -certreq command

       Use this	command	to generate a PKCS#10 Certificate Signing Request
       (CSR) and write it to a designated output destination. The contents of
       the destination should look something like the following:

	       -----BEGIN NEW CERTIFICATE REQUEST-----
	       MI...QAwXzEUMBIGA1UEAwwLcnNuQGdudS5vcmcxGzAZBgNVBAoMElUg
	       Q2...A0GA1UEBwwGU3lkbmV5MQwwCgYDVQQIDANOU1cxCzAJBgNVBACC
	       ...
	       FC...IVwNVOfQLRX+O5kAhQ/a4RTZme2L8PnpvgRwrf7Eg8D6w==
	       -----END	NEW CERTIFICATE	REQUEST-----

       IMPORTANT: Some documentation (e.g. RSA examples) claims	that the
       "Attributes" field, in the CSR is "OPTIONAL" while RFC-2986 implies the
       opposite. This implementation considers this field, by default, as
       "OPTIONAL", unless the option -attributes is specified on the command
       line.

       -alias ALIAS
	   See Common Options for more details.

       -sigalg ALGORITHM
	   The canonical name of the digital signature algorithm to use	for
	   signing the certificate. If this option is omitted, a default value
	   will	be chosen based	on the type of the private key associated with
	   the designated Alias. If the	private	key is a "DSA" one, the	value
	   for the signature algorithm will be "SHA1withDSA". If on the	other
	   hand	the private key	is an "RSA" one, then the tool will use
	   "MD5withRSA"	as the signature algorithm.

       -file FILE
	   See Common Options for more details.

       -keypass	PASSWORD
	   Use this option to specify the password which the tool will use to
	   unlock the Key Entry	associated with	the designated Alias.

	   If this option is omitted, the tool will first attempt to unlock
	   the Key Entry using the same	password protecting the	key store. If
	   this	fails, you will	then be	prompted to provide a password.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       -attributes
	   Use this option to force the	tool to	encode a "NULL"	DER value in
	   the CSR as the value	of the "Attributes" field.

       The -export command

       Use this	command	to export a certificate	stored in a key	store to a
       designated output destination, either in	binary format (if the -v
       option is specified), or	in RFC-1421 compliant encoding (if the -rfc
       option is specified instead).

       -alias ALIAS
	   See Common Options for more details.

       -file FILE
	   See Common Options for more details.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -rfc
	   Use RFC-1421	specifications when encoding the output.

       -v  Output the certificate in binary DER	encoding. This is the default
	   output format of the	command	if neither -rfc	nor "-v" options were
	   detected on the command line. If both this option and the -rfc
	   option are detected on the command line, the	tool will opt for the
	   RFC-1421 style encoding.

       Display commands

       The -list command

       Use this	command	to print one or	all of a key store entries to
       "STDOUT". Usually this command will only	print a	fingerprint of the
       certificate, unless either the -rfc or the -v option is specified.

       -alias ALIAS
	   If this option is omitted, the tool will print ALL the entries
	   found in the	key store.

	   See Common Options for more details.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -rfc
	   Use RFC-1421	specifications when encoding the output.

       -v  Output the certificate in human-readable format. If both this
	   option and the -rfc option are detected on the command line,	the
	   tool	will opt for the human-readable	form and will not abort	the
	   command.

       The -printcert command

       Use this	command	to read	a certificate from a designated	input source
       and print it to "STDOUT"	in a human-readable form.

       -file FILE
	   See Common Options for more details.

       -v  See Common Options for more details.

       Management commands

       The -keyclone command

       Use this	command	to clone an existing Key Entry and store it under a
       new (different) Alias protecting, its private key material with
       possibly	a new password.

       -alias ALIAS
	   See Common Options for more details.

       -dest ALIAS
	   Use this option to specify the new Alias which will be used to
	   identify the	cloned copy of the Key Entry.

       -keypass	PASSWORD
	   Use this option to specify the password which the tool will use to
	   unlock the Key Entry	associated with	the designated Alias.

	   If this option is omitted, the tool will first attempt to unlock
	   the Key Entry using the same	password protecting the	key store. If
	   this	fails, you will	then be	prompted to provide a password.

       -new PASSWORD
	   Use this option to specify the password protecting the private key
	   material of the newly cloned	copy of	the Key	Entry.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -storepasswd	command

       Use this	command	to change the password protecting a key	store.

       -new PASSWORD
	   The new, and	different, password which will be used to protect the
	   designated key store.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -keypasswd command

       Use this	command	to change the password protecting the private key
       material	of a designated	Key Entry.

       -alias ALIAS
	   See Common Options for more details.

	   Use this option to specify the password which the tool will use to
	   unlock the Key Entry	associated with	the designated Alias.

	   If this option is omitted, the tool will first attempt to unlock
	   the Key Entry using the same	password protecting the	key store. If
	   this	fails, you will	then be	prompted to provide a password.

       -new PASSWORD
	   The new, and	different, password which will be used to protect the
	   private key material	of the designated Key Entry.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

       The -delete command

       Use this	command	to delete a designated key store entry.

       -alias ALIAS
	   See Common Options for more details.

       -storetype STORE_TYPE
	   See Common Options for more details.

       -keystore URL
	   See Common Options for more details.

       -storepass PASSWORD
	   See Common Options for more details.

       -provider PROVIDER_CLASS_NAME
	   See Common Options for more details.

       -v  See Common Options for more details.

BUGS
SEE ALSO
AUTHOR
0.99				  2017-07-08			   GKEYTOOL(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gkeytool&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help