Keypasswd

[Rosangela Pinkard]

Thekeytool command is a key and certificate managementutility. It enables users to administer their own public/private keypairs and associated certificates for use in self-authentication (wherea user authenticates themselves to other users and services) or dataintegrity and authentication services, by using digital signatures. Thekeytool command also enables users to cache the public keys(in the form of certificates) of their communicating peers.

A certificate is a digitally signed statement from one entity(person, company, and so on), which says that the public key (and someother information) of some other entity has a particular value. Whendata is digitally signed, the signature can be verified to check thedata integrity and authenticity. Integrity means that the data hasn'tbeen modified or tampered with, and authenticity means that the datacomes from the individual who claims to have created and signed it.

The keytool command also enables users to administersecret keys and passphrases used in symmetric encryption and decryption(Data Encryption Standard). It can also display other security-relatedinformation.

The keytool command uses thejdk.certpath.disabledAlgorithms andjdk.security.legacyAlgorithms security properties todetermine which algorithms are considered a security risk. It emitswarnings when disabled or legacy algorithms are being used. Thejdk.certpath.disabledAlgorithms andjdk.security.legacyAlgorithms security properties aredefined in the java.security file (located in the JDK's$JAVA_HOME/conf/security directory).

There are two kinds of options, one is single-valued which shouldbe only provided once. If a single-valued option is provided multipletimes, the value of the last one is used. The other type ismulti-valued, which can be provided multiple times and all values areused. The only multi-valued option currently supported is the-ext option used to generate X.509v3 certificateextensions.

Braces surrounding an option signify that a default value is usedwhen the option isn't specified on the command line. Braces are alsoused around the -v, -rfc, and -Joptions, which have meaning only when they appear on the command line.They don't have any default values.

Brackets surrounding an option signify that the user is promptedfor the values when the option isn't specified on the command line. Forthe -keypass option, if you don't specify the option on thecommand line, then the keytool command first attempts touse the keystore password to recover the private/secret key. If thisattempt fails, then the keytool command prompts you for theprivate/secret key password.

-addprovider name[-providerarg arg]: Adds a security provider byname (such as SunPKCS11) with an optional configure argument. The valueof the security provider is the name of a security provider that isdefined in a module.

For compatibility reasons, the SunPKCS11 provider can still be loadedwith -providerclass sun.security.pkcs11.SunPKCS11 even ifit is now defined in a module. This is the only module included in theJDK that needs a configuration, and therefore the most widely used withthe -providerclass option. For legacy security providerslocated on classpath and loaded by reflection,-providerclass should still be used.

Use the -gencert command to generate a certificate as aresponse to a certificate request file (which can be created by thekeytool -certreq command). The command reads the requesteither from infile or, if omitted, from the standard input,signs it by using the alias's private key, and outputs the X.509certificate into either outfile or, if omitted, to the standardoutput. When -rfc is specified, the output format isBase64-encoded PEM; otherwise, a binary DER is created.

The -sigalg value specifies the algorithm that should beused to sign the certificate. The startdate argument is thestart time and date that the certificate is valid. The daysargument tells the number of days for which the certificate should beconsidered valid.

Use the -genkeypair command to generate a key pair (apublic key and associated private key). When the -signeroption is not specified, the public key is wrapped in an X.509 v3self-signed certificate and stored as a single-element certificatechain. When the -signer option is specified, a newcertificate is generated and signed by the designated signer and storedas a multiple-element certificate chain (containing the generatedcertificate itself, and the signer's certificate chain). The certificatechain and private key are stored in a new keystore entry that isidentified by its alias.

The -keyalg value specifies the algorithm to be used togenerate the key pair, and the -keysize value specifies thesize of each key to be generated. The -sigalg valuespecifies the algorithm that should be used to sign the certificate.This algorithm must be compatible with the -keyalgvalue.

The -signer value specifies the alias of aPrivateKeyEntry for the signer that already exists in thekeystore. This option is used to sign the certificate with the signer'sprivate key. This is especially useful for key agreement algorithms(i.e. the -keyalg value is XDH,X25519, X448, or DH) as thesekeys cannot be used for digital signatures, and therefore a self-signedcertificate cannot be created.

The -dname value specifies the X.500 Distinguished Nameto be associated with the value of -alias. If the-signer option is not specified, the issuer and subjectfields of the self-signed certificate are populated with the specifieddistinguished name. If the -signer option is specified, thesubject field of the certificate is populated with the specifieddistinguished name and the issuer field is populated with the subjectfield of the signer's certificate. If a distinguished name is notprovided at the command line, then the user is prompted for one.

The value of -keypass is a password used to protect theprivate key of the generated key pair. If a password is not provided,then the user is prompted for it. If you press theReturn key at the prompt, then the key password is setto the same password as the keystore password. The -keypassvalue must have at least six characters.

With the first form, the issue time is shifted by the specified valuefrom the current time. The value is a concatenation of a sequence ofsubvalues. Inside each subvalue, the plus sign (+) means shift forward,and the minus sign (-) means shift backward. The time to be shifted isnnn units of years, months, days, hours, minutes, or seconds(denoted by a single character of y, m,d, H, M, or Srespectively). The exact value of the issue time is calculated by usingthe java.util.GregorianCalendar.add(int field, int amount)method on each subvalue, from left to right. For example, the issue timecan be specified by:

With the second form, the user sets the exact issue time in twoparts, year/month/day and hour:minute:second (using the local timezone). The user can provide only one part, which means the other part isthe same as the current date (or time). The user must provide the exactnumber of digits shown in the format definition (padding with 0 whenshorter). When both date and time are provided, there is one (and onlyone) space character between the two parts. The hour should always beprovided in 24-hour format.

The value of -keyalg specifies the algorithm to be usedto generate the secret key, and the value of -keysizespecifies the size of the key that is generated. The-keypass value is a password that protects the secret key.If a password is not provided, then the user is prompted for it. If youpress the Return key at the prompt, then the keypassword is set to the same password that is used for the-keystore. The -keypass value must contain atleast six characters.

Use the -importcert command to read the certificate orcertificate chain (where the latter is supplied in a PKCS#7 formattedreply or in a sequence of X.509 certificates) from -filefile, and store it in the keystore entryidentified by -alias. If -file fileis not specified, then the certificate or certificate chain is read fromstdin.

The keytool command can import X.509 v1, v2, and v3certificates, and PKCS#7 formatted certificate chains consisting ofcertificates of that type. The data to be imported must be providedeither in binary encoding format or in printable encoding format (alsoknown as Base64 encoding) as defined by the Internet RFC 1421 standard.In the latter case, the encoding must be bounded at the beginning by astring that starts with -----BEGIN, and bounded at the endby a string that starts with -----END.

You import a certificate for two reasons: To add it to the list oftrusted certificates, and to import a certificate reply received from acertificate authority (CA) as the result of submitting a CertificateSigning Request (CSR) to that CA. See the -certreq commandin Commands forGenerating a Certificate Request.

The type of import is indicated by the value of the-alias option. If the alias doesn't point to a key entry,then the keytool command assumes you are adding a trustedcertificate entry. In this case, the alias shouldn't already exist inthe keystore. If the alias does exist, then the keytoolcommand outputs an error because a trusted certificate already existsfor that alias, and doesn't import the certificate. If-alias points to a key entry, then the keytoolcommand assumes that you're importing a certificate reply.

Use the -importpass command to imports a passphrase andstore it in a new KeyStore.SecretKeyEntry identified by-alias. The passphrase may be supplied via the standardinput stream; otherwise the user is prompted for it. The-keypass option provides a password to protect the importedpassphrase. If a password is not provided, then the user is prompted forit. If you press the Return key at the prompt, then thekey password is set to the same password as that used for thekeystore. The -keypass value must contain atleast six characters.

When the -srcalias option is provided, the commandimports the single entry identified by the alias to the destinationkeystore. If a destination alias isn't provided with-destalias, then -srcalias is used as thedestination alias. If the source entry is protected by a password, then-srckeypass is used to recover the entry. If-srckeypass isn't provided, then the keytoolcommand attempts to use -srcstorepass to recover the entry.If -srcstorepass is not provided or is incorrect, then theuser is prompted for a password. The destination entry is protected with-destkeypass. If -destkeypass isn't provided,then the destination entry is protected with the source entry password.For example, most third-party tools require storepass andkeypass in a PKCS #12 keystore to be the same. To create aPKCS#12 keystore for these tools, always specify a-destkeypass that is the same as-deststorepass.

3a8082e126