Using keytool in Security tools

Symbian OS provides a key store, which is a repository of private keys that can be programmatically retrieved and used to accomplish a variety of tasks. The key store is initially empty. To insert private keys and manipulate them we suggest the use of the keytool.

The Symbian keystore is meant to store private keys in a PKI setting. Keys for symmetric cryptography cannot be stored in the keystore.

Keytool is an epoc shell program which manipulates the key store. Its main features are:

List the content of a key store
Insertion and Removal of private keys
Manipulation of the registered users for a given key, ownership, usages, etc.
Support for multiple key store implementations

The keytool source code can be found in the security sub-system in the following directory: .../filetokens/test/keytool. The keytool must be used from an epoc shell. You can start it using eshell.exe.

We shall go through the various tool usages. Typing keytool results in a list of supported commands. To access more information about a specific command, the list command for instance, we can just type:

> keytool – h list

The following is a summary of commands available to use with keytool.

Full command	Shortened command	Description
`-liststores`	`-ls`	Lists the available key store implementations.
`-list`	`-l`	Displays the contents of the key store.
`-import`	`-i`	Imports private keys in the store.
`-remove`	`-r`	Removes a key from the key store.
`-setuser`	`-s`	Set a user.
`-setallusers`	`-a`	Set multiple users.
`-setmanager`	`-m`	Set a manager.
`-removeuser`	`-ru`	Remove a user.

Note that long commands, for example, liststores, list and setuser are not case-sensitive but short commands, for example -ls, -l, -a,-s and -m are case sensitive.

To read commands from an “inputfile” and give the output in “outputfile”, use the following command:

> keytool <inputfile> <outputfile>

The file name should be mentioned with the path. If the tool cannot open the “inputfile” or cannot create the output file, it will turn to interactive mode and display the general help command. The input file can contain multiple commands but each command should be separated by a new line character.

If the commands are given incorrectly or in the wrong sequence, for example keytool -store -l or keytool -i -l, the tool displays the default general help command.

In interactive mode, any command called with the -p option, displays full details and waits for key input. In non-interactive mode, the option is ommitted.

In the following sections we shall describe each supported command in details.

The Symbian key store architecture allows devices to have multiple, coexisting, keystore implementations. All implementations are accessed through an abstraction layer: the “unified keystore”.

The keytool fully supports multiple key store implementations with the option –store which can be used to specify a particular key store implementation which a command must use. To see a list of all available key store implementations the command –listtores or -ls for short, can be used. For example we can say:

> keytool – ls

And obtain as result an output similar to:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
[0] Store Label: On-device key store
Version: 1.00  Serial Number: 0        Manufacturer: Symbian Software Ltd.

We have an entry for each key store implementation. The number in brackets represents the key store index which we will use to refer to a specific key store implementation in the –store option. We then have a label, a human readable description of the implementation. Some meta-data follows: the version, serial number and manufacturer of a given implementation. In the above case we have only one key store implementation, the standard on device store provided by Symbian.

With this knowledge we can use the –store option to specify the key store implementation a command must use.

The list command is used to display the content of the key store. It can be used to display the overall content of all key store implementations, to display the content of a specific key store implementation, or to display details about a specific key if we know its label.

Listing the content of all key store implementations

To see all the private keys available on the device we can use the command:

> keytool -list

The output, depending on the actual keys present on the device will look similar to:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Store Label: Software key store
gm0 is a 512 bits RSA key 

Store Label: Software key store
gm1 is a 512 bits DSA key 

Store Label: Software key store
Tls Test RSAKey is a 1024 bits RSA key

In this case we have two RSA keys and one DSA key. The above output is essential. You can get more information by using the – details (-d for short) option:

keytool –l –d

keytool –l –d
Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Store Label: Software key store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
        Algorithm: RSA Size: 512  bits
        Usage : PKCS15 DecryptSignSignRecover    Code: 0xe 
        Owner : 0x101f7e95 
        User : 0x101f7e95 
        Access flags: Extractable 
        ID: 4d 15 e9 01 c6 ea ff a0 11 57 05 60 f4 ba 0c 0f 58 db ae e7 
        Label: gm0
        Native: Yes 
        Start date: not set  End date: not set

In the following table we shall analyse the output in some detail.

Output type	Description
Algorithm	The algorithm field shows us what kind of key we have. The valid values are RSA and DSA.
Size	The size of the key in bits. For instance, in the example above, we have three RSA keys with sizes ranging from 512 to 2048 bits. The maximum allowed key size, as of now, is 2048 bits. This may change in the future.
Usage	The usage attribute specifies the tasks which we can perform with the given key. Valid values for usage are: sign and signrecover for DSA keys sign, signrecover, decrypt and unwrap for RSA keys Usage attributes are set during key import, attempts to set invalid usages will result in an error.
Owner	Each key belongs to a specific UID. This UID represents the owner of the key. Typically the owner of a key is the application which imported the key. Only the owner of the key can remove it from the key store. Additionally only the owner can set the users of a key. The owner of the key can be changed by `writedevicedata` after it is imported, using `keytool -m <keyname>` All processes that have `writedevicedata` capability can manipulate the keys.
User	The user attribute is a list of application UIDs. Each of those UIDs are allowed to use the key to perform a task allowed by its usage attribute, e.g. sign some data, verify a signature, etc. Each key user belongs to a specific UID, which is, by default the process owner. It can be set to `all` by using `keytool – a <keyname>`.
Access Flags	Access flags reflect those defined in the PKCS#11 standard. We have: 1. `Sensitive` – The key can only be exported in encrypted form. A key marked as sensitive might have been imported either from a cleartext or encrypted source. 2. `Extractable` – The key can be exported. 3. `AlwaysSensitive` – The key has never existed outside the keystore in unencrypted form, to the best of our knowledge. This access flag is set automatically by the key store. You do not have explicit access to it. It will be set only if the key has been imported as Sensitive from an encrypted source. 4. `NeverExtractable` – The key cannot be exported, and has never existed outside the keystore. This implies that the key was created on the device. 5. `Local` – The key was created on the device, rather than being imported. The access flag can be set only during import and the only the values `Sensitive` and `Extractable` are available to the users. See the section Importing private keys.
ID	A unique identifier for the key. It is in hexadecimal format.
Label	The key label. A human readable handle for the key.
Native	Specifies whether cryptographic operations involving the key will be performed on the cryptographic token or outside it. For instance a hardware key store might provide key storage but no facilities for encryption which will then be executed outside the token (native is false). This is always true for the Symbian OS file key store implementation.
Start and End date	The period of time when the key is actually valid. The key cannot be used outside this time frame.

Listing the content of a specific key store implementation

If we are interested only in the content of a specific key store implementation, we can restrict the list command to that implementation using the – store option. Suppose we are interested in the content of the key store implementation with index 0 (see the section Working with multiple keystore implementations for details on how to list the available key store implementations) we can issue the command:

keytool –store 0 –list

Depending on the content of the key store implementation with index 0 we will get output similar to:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
    Algorithm: RSA Size: 512 bits
    Usage: Pkcs15 Sign   Code: 0x4
    Owner: 0x101f7e95
    User: 0x101f7e95
    Access Flags: Extractable
    ID: …
    Label: rsa1
    Native: Yes
    Start Date: not set     End Data: not set

If we try to specify a non-existing key store implementation an error will occur:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
The specified keystore implementation does not exist.
Error during list!
Error code KErrArgument.

Displaying information about a specific private key

It is possible to display information about a specific key of which we know the label. This is useful, for instance, when the key store contains a significant amount of keys and we are only interested in a particular one. Suppose we want to display information about a key with label “rsa1” we can issue the command:

keytool –list rsa1 -d

Remember that labels are case sensitive. We should get an output similar to:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
    Algorithm: RSA Size: 512 bits
    Usage: Pkcs15 Sign   Code: 0x4
    Owner: 0x101f7e95
    User: 0x101f7e95
    Access Flags: Extractable
    ID: …
    Label: rsa1
    Native: Yes
    Start Date: not set     End Data: not set

If no key in the key store corresponds to the given label an error will occur:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Cannot find the specified key.

Wildcards

The list commands supports wildcards (“*” and “?”) on key labels. For instance the following command lists information about all keys whose label contains the string “dsa”:

> c:\>keytool – l *dsa*

Internal name	Algorithm	Key size
`ECipherDES_CBC`	`DES`	`64 bits`
`ECipher3DES_CBC`	`Triple DES`	`192 bits`
`ECipherRC2_CBC_40`	`RC2`	`Effective key length 1024 bits`
`ECipherRC2_CBC_128`	`RC2`	`Effective key length 1024 bits`
`ECipherRC2_CBC_40_16`	`RC2`	`Effective key length 128 bits`
`ECipherRC2_CBC_128_16`	`RC2`	`Effective key length 128 bits`

The Symbian key store supports two types of key, DSA keys and RSA keys. You can use the keytool to import private keys stored into files. The keys must be stored in pkcs#8 DER encoded format. No other type of encoding is supported, this means that you cannot import keys stored in PEM format. The pkcs#8 encoding allows private keys to be stored either in cleartext or encrypted using a password based cryptography scheme (PBE). See the table above for a list of the PBE schemes supported by Symbian OS.

Suppose the keystore is empty, you want to populate it by importing private keys which are stored somewhere in your Symbian device file system. Let us start by importing a RSA private key stored in the file pkcs8rsa.001:

> keytool – import c:\tkeystore\data\pkcs8rsa.001

Since the keystore was empty, we have to create a passphrase for it. A passphrase is used to PBE encrypt the actual storage which the keystore uses as back-end. We will see a dialog similar to this one:

Choose a passphrase and enter it. The resulting output should be similar to:

Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Key imported successfully.
    Algorithm: RSA Size: 512 bits
    Usage: Pkcs15 Sign   Code: 0x4
    Owner: 0x101f7e95
    User: 0x101f7e95
    Access Flags: Extractable
    ID: 4d 15 e9 01 …
    Label: c:\tkeystore\data\pkcs8rsa.001
    Native: Yes
    Start Date: not set     End Data: not set

A key always has a label associated with it. A label can be specified during the import operation with the – label option, if this option is not present the full path to the key file is taken as label, in this case we have c:\tkeystore\data\pkcs8rsa.001. Labels must be unique within a specific key store implementation. If a label is not unique, an error occurs, for instance if the key store contains a certificate with label abc:

c:\>keytool –list abc
Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
abc is a 1024 bits RSA key

If we try to import a key with the same label an error will occur:

c:\>keytool –label abc –import c:\tkeystore\data\pkcs8rsa
Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
The given label is invalid, or already present in the keystore.
Error code: KErrAlreadyExist

However, this happens because we are trying to insert the key in a key store implementation where the same label already exists. Remember that if we do not specify the key store implementation to use in a command, we use the first (index 0) by default. It is certainly possible to insert the key with label abc in the key store implementation with index 1 (if such an implementation exists), e.g.

c:\>keytool –label abc –store 1 –import c:\tkeystore\data\pkcs8rsa 
Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Key imported successfully
    Algorithm: RSA Size: 512 bits
    Usage: Pkcs15 Sign   Code: 0x4
    Owner: 0x101f7e95
    User: 0x101f7e95
    Access Flags: Extractable
    ID: 4d 15 e9 01 …
    Label: abc
    Native: Yes
    Start Date: not set     End Data: not set

Setting key attributes

During key import a number of key attributes can be specified. Most key attributes can only be specified during import. The following options are available to the import command:

access

Specifies the access attribute of the key. The only valid values are Extractable for a key which can be exported and Sensitive for a key which can only be exported in encrypted form. Other access flags are set automatically by the key store.

usage

Specifies the key usage as defined in the PKCS#15 standard. The valid values depend on the type of the key being imported:

DSA The valid values are sign and signrecover which from the keystore point of view are identical. External applications might consider them differently though.
RSA The valid values are sign, signrecover, decrypt and unwrap.

Wildcards

If you need to import a large set of keys, the procedure above might be tiresome. The keytool offers an alternative: wildcards. It is possible to specify a set of key files to be imported using the wild cards “*” and “?”. For instance, suppose you want to import all the RSA key files in the directory c:\tkeystore\data, you can do that, depending on the actual file names, with a command similar to:

> keytool – import c:\tkeystore\data\pkcs8rsa*.001

The imported keys will have the file names as labels.

Importing cleartext private keys

The pkcs8 private key format allows both cleartext and encrypted content. All the previous examples refer to cleartext keys. In this case no further action is required from the user.

Importing encrypted private keys

Importing encrypted private keys requires further user interaction. This is because the keys are PBE encrypted and it is necessary to decrypt them to perform a key import. The user is, therefore, asked the passphrase for a given encrypted key.

Note: either secdlg or tsecdlg need to be in \epoc32\release\winscw\udeb. However, if both of them are there, it will cause a panic.

Private keys can be removed from the key store using the -remove command (-r for short). If we have a key labelled abc in the key store:

c:\>keytool –list abc
Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Key imported successfully
    Algorithm: RSA Size: 512 bits
    Usage: Pkcs15 Sign   Code: 0x4
    Owner: 0x101f7e95
    User: 0x101f7e95
    Access Flags: Extractable
    ID: 4d 15 e9 01 …
    Label: abc
    Native: Yes
    Start Date: not set     End Data: not set

We can remove the key using the following command:

c:\>keytool –remove abc
Symbian OS KeyStore Manipulation Tool
Copyright (c) 2004 Symbian Software Ltd.  All rights reserved.
Key deleted successfully.

Note: The keytool can only remove keys which were imported using the keytool or the TechView key store UI. Other keys will have a different owner and cannot, therefore, be removed in this fashion.

The remove command supports the “*” and “?” wildcards on key labels. All the keys whose labels match the given pattern will be removed, e.g.: c:\>keytool – r *rsa* will remove all the keys whose label contains the string “rsa”.

Either a single user is associated with a key in the keystore or it is accessible to ALL. The list is made of UIDs identifying applications that can use a key. Only these applications have access to the key, by default these are also the applications which can see the key, although an application can programmatically list keys it cannot use by providing a suitable filter.

Only the key owner can modify the users associated with a given key. The keytool provides a number of commands to manipulate the users of a given key. In the following sections we shall describe each of them in some details.

You can use the following command to set a user:

> keytool – setuser 0x1234abcd MyRsaKey

Note: you can set only one user at a time.

Output from a successful attempt at setting a user may be similar to the following:

User set successfully.
Store Label: Software key store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
        Algorithm: DSA Size: 512  bits
        Usage : PKCS15 Sign  Code: 0x4 
        Owner : 0x10281c32 
        User : 0x1234abcd 
        Access flags: Extractable 
        ID: bb 6d 53 c5 06 93 0b 45 14 11 39 df 0a 3f fc 5b b0 17 ba 28 
        Label: abc
        Native: Yes 
        Start date: not set  End date: not set

You can use the following command to set multiple users:

> keytool – setallusers

Output from a successful attempt at setting multiple users may be similar to the following:

Users set successfully.
Store Label: Software key store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
        Algorithm: DSA Size: 512  bits
        Usage : PKCS15 Sign  Code: 0x4 
        Owner : 0x10281c32 
        User : ALL 
        Access flags: Extractable 
        ID: bb 6d 53 c5 06 93 0b 45 14 11 39 df 0a 3f fc 5b b0 17 ba 28 
        Label: abc
        Native: Yes 
        Start date: not set  End date: not set

You can use the following command to set a manager:

> keytool – setmanager abc

Output from a successful attempt at setting a manager may be similar to the following:

Manager set successfully.
Store Label: Software key store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
        Algorithm: DSA Size: 512  bits
        Usage : PKCS15 Sign  Code: 0x4 
        Owner : WriteDeviceData 
        User : ALL 
        Access flags: Extractable 
        ID: bb 6d 53 c5 06 93 0b 45 14 11 39 df 0a 3f fc 5b b0 17 ba 28 
        Label: abc
        Native: Yes 
        Start date: not set  End date: not set

You can remove users using the following command:

> keytool – removeuser abc

In this case existing user will be removed and keytool will be set as a default user Command:

User removed successfully.
Store Label: Software key store
Version: 1.00      Serial Number: 0    Manufacturer: Symbian Ltd. Store Type: Read only
        Algorithm: DSA Size: 512  bits
        Usage : PKCS15 Sign  Code: 0x4 
        Owner : WriteDeviceData 
        User : 0x10281c32  (KeyTool)
        Access flags: Extractable 
        ID: bb 6d 53 c5 06 93 0b 45 14 11 39 df 0a 3f fc 5b b0 17 ba 28 
        Label: abc
        Native: Yes 
        Start date: not set  End date: not set

How to manipulate the key store

Overview

Using the keytool

Working with multiple keystore implementations

The list command

Listing the content of all key store implementations

Listing the content of a specific key store implementation

Displaying information about a specific private key

Wildcards

Importing private keys

Setting key attributes

Wildcards

Importing cleartext private keys

Importing encrypted private keys

Removing keys

Manipulating a private key user list

Setting users and managers

Removing users