--- name: "gkeytool-4.7" section: "1" platform: "linux" package: "gcj-4.7-jre-headless" version: "4.7.2-3" release: "Debian 7 (Wheezy)" platforms: ["linux"] url: "https://new.carta.tech/gkeytool-4.7" --- # gkeytool-4.7(1) Manage private keys and public certificates ## 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 *COMMAND*s 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 **OPTION**s 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