Appendix A       Using TokenKeyTool



Starting TokenKeyTool

---

The TokenKeyTool manipulates TokenKeyStores and collections of TokenKeyStores. It is invoked as:

java com.iplanet.trustbase.security.store.TokenKeyTool [ <globalswitch>* ] [ <command> ]

Commands are strings of alphanumeric characters, while switches are '-' symbols followed directly by a string of alphanumeric characters, and possibly followed by a single argument [ arguments may be not present, alphanumeric, or numeric, depending on the switch ]

If a command is passed on the command line, then it is executed directly, with the switches passed on the command line, and the VM exits. If no command is passed on the command line, then a shell mode is entered, into which commands may be entered as:

<command> [ <localswitch>* ]

Each command in the shell mode is executed with a set of switches which is comprised of any local switches, plus any global switches which were passed in on the original command line [ or set with the setglobals command ]. If any switch is specified in both local and global switches, the local switch overrides the global switch. Thus, if the TokenKeyTool is invoked as below, then the global switches will specify a TokenKeyStoreManager and TokenKeyStore which will be used by default in all operations [ unless the global switches are overridden, or new defaults are subsequently set ]

java com.iplanet.trustbase.security.store.TokenKeyTool -domainspace "file:~/domains" -manager m -store defaultStore

Commands are broadly divided into those that deal with TokenKeyStoreManagers and tokenKeyStores as a whole, those that deal with the contents of TokenKeyStores, utility commands that perform cryptographic operations with the objects in TokenKeyStores, and a few miscellaneous commands useful for examining the TokenKeyTool environment.

There is also a script for running TokenKeyTool

cd ../opt/ittm/Scripts

./runtokenkeytool

Commands for dealing with TokenKeyStoreManagers

openstoremanager -domainspace <domainspace> -manager <localname> -nodefault

opens a TokenKeyStoreManager, associating it with a nickname for convenient reference, and optionally making the opened TokenKeyStoreManager the default.

• <domainspace>: a URL describing a trust domain space. The URL will be used to create a TrustDomainManager. Its protocol determines the type of TrustDomainManager which will be created, and consequently where the TrustDomains are stored. If a file: URL is given then the URL must refer to a directory, within which individual TrustDomains will be stored as files named <TrustDomainName>.domain

• <localname>: a nickname by which the TrustDomainManager will be referred to in any subsequent operations in the TokenKeyTool

• -nodefault: if specified then the TokenKeyStoreManager instance will not be made the default TokenKeyStoreManager for subsequent operations

Some example openStoreManager commands

openstoremanager -domainspace "file:domains" -manager m

This one opens a TokenKeyStoreManager backing on to a FileTrustDomainManager which stores TrustDomain definitions in the directory "domains" relative to the current working directory. The TokenKeyStoreManager will be referred to as 'm' hereinafter

openstoremanager -domainspace "file:///export/domains" -manager m

Similar to the previous command, but the TrustDomains are stored in directory

"/export/domains"

openstoremanager -domainspace "jss:jss" -manager m

This opens a special TokenKeyStoreManager which uses a TrustDomainManager which is dynamically constructed from the contents of a JSS permanent store, and any attached PKCS#11 tokens. It can be used to access cryptographic objects created by programs which use NSS but are not TrustDomains aware

setdefaultstoremanager -manager <localname>

Sets an already loaded TokenKeyStoreManager as the default for subsequent operations which require a TokenKeyStoreManager, but do not specify one explicitly

• <localname>: the nickname of an open TokenKeyStoreManager

  unsetdefaultstoremanager

unsets any default TokenKeyStoreManager : after this operation any operation requiring a TokenKeyStoreManager will have to specify it explicitly, or a new default must be set using setDefaultStoreManager

liststores [ -manager <localname> ]

lists the TokenKeyStores managed by a TokenKeyStoreManager. If no TokenKeyStoreManager is explicitly specified, then the default is used

• <localname>: the nickname of an open TokenKeyStoreManager

Commands for dealing with TokenKeyStores

These commands operate on objects in TokenKeyStores [ and their corresponding persistent representations in the associated TrustDomain ]. Each command can explicitly specify the TokenKeyStore to be operated upon, and the TokenKeyStoreManager responsible for that TokenKeyStore, or it can rely upon defaults having been set, or the global switches containing appropriate references to a TokenKeyStoreManager and TokenKeyStore. The following two switches can be used with any of the commands dealing with TokenKeyStores to explicitly specify a TokenKeyStore and TokenKeyStoreManager

[ -store <storename> [ -manager <localname> ] ]

• <storename>: name of the new store

• <localname>: the nickname of an open TokenKeyStoreManager

createstore -store <storename> [ -tokentype <tokentype:JSS> ] [ -pathvalidation <validationlist> ] [ -nodefault ]

Creates a new TokenKeyStore in a trust domain space associated with the TokenKeyStoreManager, which is either specified explicitly, or is a default. The type of the Token which will be used to activate the cryptographic objects created and imported into the new TrustDomain associated with the new TokenKeyStore may optionally be specified, as may the list of identifiers of CertificatePathValidators to be used to validate certificate chains in the TrustDomain

• <storename>: name of the new store

• <validationlist>: colon separated list of certificate path validation algorithms to be used for validating certificate chains in the TrustDomain. Defaults if not given

• <tokentype>: type of Token to use for crypto operations. Defaults if not given

• -nodefault: if given the new TokenKeyStore will not be made the default TokenKeyStore for subsequent operations

deletestore

Deletes a TokenKeyStore and it's associated TrustDomain from the trust domain space associated with the TokenKeyStoreManager specified explicitly or by default

setdefaultstore -store <storename> [ -manager <localname> ]

Sets the default TokenKeyStore to be used in subsequent commands where a TokenKeyStore is not specified explicitly

• <storename>: name of the store to make the default

  unsetdefaultstore

Unsets the default TokenKeyStore : subsequent commands requiring a TokenKeyStore will have to specify one explicitly, or use setDefaultStore first

listaliases

List all the aliases in use in a TokenKeyStore

listcerts [-alias <alias> | (-issuer <issuerDN> -serial <serial#>)]

List TrustedCertificateEntrys from a TokenKeyStore. If a single certificate is referenced, either by alias or by issuer and serial number, then just that certificate's details are printed. If no single certificate is referenced, then the certificates from TrustedCertificateEntrys are printed

• <alias>: a TrustedCertificateEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

examinecerts [ -file <filename> ]

Describe the certificates contained in an archive. The archive may contain one or more certificates in X.509 DER, Base-64 X.509 DER, PKCS#7 DER, or Base-64 PKCS#7 DER format

• <filename>: the name of a file to read certificates from. If no filename is given, then certificates will be read from stdin [i.e. should be pasted into the terminal ]

  listkeys [-alias <alias> | (-issuer <issuerDN> -serial <serial#>)]

List KeyEntrys from a TokenKeyStore. If a single KeyEntry is referenced, by alias or by the issuer and serial number of the subject cert of it's certificate chain, then just that KeyEntry's details are printed. If no single KeyEntry is referenced, then a description of all KeyEntrys is printed

• <alias>: a TrustedCertificateEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

genkey -dname <subjectDN> [-keysz <keysize:1024>] [-keyalg <keyalg:RSA>]]

Generate a new KeyPair, and a self-signed certificate to accompany it in the resulting KeyEntry

• <subjectDN>: The RFC2253 encoded subject distinguished name of the generated self-signed certificate

• <keysz>: The size of key to generate. Defaults to 1024 bits

• <keyalg>: The key algorithm. Defaults to RSA. DSA is the only other possible value

certreq ( -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) ) [ -dname <subjectDN> ] [ -file <filename> ] [ -der ]

Create a PKCS#10 certificate request using the PrivateKey from and existing KeyEntry. The KeyEntry may be identified using an alias, or alternatively by the issuer and serial number of it's associated subject certificate

• <alias>: a KeyEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

• <subjectDN>: The RFC2253 encoded subject distinguished name of the generated self-signed certificate

• <filename>: The name of a file to save the PKCS#10 request in. If not given, it will be printed to the terminal

• -der: write output in raw DER rather than base-64 encoded DER [ works best with -file ]

deletecert [ -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) ]

Delete a TrustedCertificateEntry. The TrustedCertificateEntry to delete can be identified either by alias, or by issuer and serial number

• <alias>: a TrustedCertificateEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

deletekey [ -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) ]

Delete a KeyEntry. The KeyEntry to delete can be identified either by alias, or by issuer and serial number

• <alias>: a TrustedCertificateEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

addalias ( -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) ) -newalias <newalias>

Add an alias to an entry [ either a KeyEntry or a TrustedCertificateEntry ]. The entry can be identified either by alias, or by issuer and serial number. Aliases are unique in TrustDomains, so an attempt to add an alias which already exists in the TrustDomain associated with the TokenKeyStore in which the entry is present will fail.

• <alias>: an entry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

• <newalias>: the new alias to add

removealias -alias <alias>

Remove and alias from an entry. The entry may be identified by either the alias to be removed or by issuer and serial number

• <alias>: an entry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

importtrustedcerts [ -file <filename> ]

Import trusted certificates from an archive containing one or more certificates, encoded in X.509 DER, Base-64 X.509 DER, PKCS#7 DER, or Base-64 PKCS#7 DER. All the certificates in the archive will be added to the TrustDomain as TrustedCertificateEntrys

• <filename>: the name of a file containing the certificate archive. If not given, the archive will be read from stdin

exportcerts ( -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) ) [-file <filename>] [-der] [-pkcs7]

Export certificates from a TrustedCertificateEntry or a KeyEntry. The entry may be referenced using an alias or an issuer and serial number. The certificates can be exported as X.509 DER, Base-64 X.509 DER, PKCS#7 DER, or Base-64 PKCS#7 DER

• <alias>: an entry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

• <filename>: the name of a file to write the output to. If not specified, the output will be written to the terminal, which will be noisy with -der

• <-der>: write output as DER rather than Base-64 DER

• <-pkcs7>: write output as a pkcs#7 certificate archive

importkeychain [ ( -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) ) ] [-file <filename> ]

Import a chain of certificates to a KeyEntry. The KeyEntry may be referenced implicitly, or explicitly by an alias or by an issuer and serial number. If referenced implicitly, the public key in the subject certificate of the supplied chain will be used to select a KeyEntry. The operation will fail if more than one KeyEntry contains the same key, and in that case, the KeyEntry must be specified explicitly. The existing chain of certificates will be replaced by the chain retrieved from the archive, which may be encoded in X.509 DER, Base-64 X.509 DER, PKCS#7 DER, or Base-64 PKCS#7 DER. If the archive contains an incomplete chain of certificates, then an attempt will be made to complete the chain from certificates already in the store, but if this cannot be done then the import operation will fail

• <alias>: a KeyEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

• <filename>: the name of a file to read the certificates from. If not specified, the output will be read from the terminal

• <-der>: write output as DER rather than Base-64 DER

• <-pkcs7>: write output as a pkcs#7 certificate archive

Utility commands

These commands do not directly manipulate the objects in a TokenKeyStore, or a TokenKeyStoreManager, but do use the cryptographic objects in a TokenKeyStore for various useful operations. They will hopefully be useful for testing purposes

validate [ -file <filename> ]]

Validate a chain of certificates in a TrustDomain. A chain of certificates is valid in a TrustDomain if it correctly signed, has somewhere in it's length a certificate which has a TrustedCertificateEntry, and passes the constraints imposed by the list of CertificatePathValidators associated with the TrustDomain

• <filename>: the name of a file to read the certificates from. If not specified, the output will be read from the terminal

verify -data <filename> -sig <filename> -sigalg <sigalg> ( -alias <alias> | (-issuer <issuerDN> -serial <serial#> ) )

Verify a digital signature using a key from a TokenKeyStore. Both source data and the signature are given, and the PublicKey contained in the subject cert of the KeyEntry referenced by alias or by issuer and serial number is used to verify the signature

• <alias>: a KeyEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

• -data <filename>: the name of a file to read source data from. must be specified

• -sig <filename>: the name of a file to read the signature from. must be specified

• <sigalg>: JCA name of the Signature algorithm to use

sign -data <filename> -sig <filename> -sigalg <sigalg> ( -alias <alias> | ( -issuer <issuerDN> -serial <serial#> ) )

Generate a digital signature [ which may then be verified with verify ]. The source data is signed using the PrivateKey contained in the KeyEntry referenced by an alias or an issuer and serial number. The generated signature is written to a file

• <alias>: a KeyEntry alias

• <issuerDN>: RFC2253 encoded issuer distinguished name

• <serial#>: cert serial number. decimal or hex preceded by 0x

• -data <filename>: the name of a file to read source data from. must be specified

• -sig <filename>: the name of a file to write the signature to. must be specified

• <sigalg>: JCA name of the Signature algorithm to use

digest -data <filename> -digest <filename> -digestalg <digalg>

Generate a message digest from some source data

• -data <filename>: the name of a file to read source data from. must be specified

• -digest <filename>: the name of a file to write the digest to. must be specified

• <digalg>: JCA name of the Signature algorithm to use

httpsclient [-host <host:localhost>] [-port <port:443>] [-clientcert <certalias>]

Perform an HTTPS client connection. Server certificates will be validated in the TrustDomain associated with the chosen TokenKeyStore, and client certificates will be chosen from the KeyEntrys in the TokenKeyStore. A simple GET will be issued over the SSL connection, and the results printed to the terminal. If the Java system property ssl.debug is defined then additional debugging information concerning the server certificate validation and the client certificate selection will be printed

• <host>: hostname to connect to. defaults to localhost

• <port>: port to connect to. defaults to 443

• <certalias>: client certificate alias. if not specified, a suitable KeyEntry, which matches the server's specification of acceptable issuers, will be used

  httpsserver [-port <port:443>] -servercert <certalias> [-clientauth]

Await HTTPS client connections, returning a simple html file whatever request is received. Client certificates will be validated in the TrustDomain associated with the TokenKeyStore, and server certs will be chosen from the KeyEntrys in the TokenKeyStore.

• <port>: port to listen on. Defaults to 443 [ which may require root privileges ]

• <certalias>: server certificate alias. must be specified.

• -clientauth if specified, a client certificate will be requested.

Miscellaneous commands

Some miscellaneous and useful commands for working with the TokenKeyTool and it's environment

setglobals [<anyswitch>*]

Any switches specified here will be implicitly passed to subsequent commands [ although the same switches passed explicitly to those commands, as local switches, will override the global switches ]

listproviders

• List the properties content of all installed JCA Providers