Importing -Private Keys

diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-2E02B840-FF86-5535-BA0E-5C4C3B600E9B.dita --- a/Symbian3/PDK/Source/GUID-2E02B840-FF86-5535-BA0E-5C4C3B600E9B.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-2E02B840-FF86-5535-BA0E-5C4C3B600E9B.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,135 +1,136 @@ - - - - - -Importing -Private Keys -

The Symbian key store supports two types of key, DSA keys and RSA keys. -You can use 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).

Suppose the keystore is empty and you want to populate it by importing -private keys which are stored in your Symbian device file system. Start by -importing an RSA private key stored in the file pkcs8rsa.001:

keytool –import c:\keystore\data\pkcs8rsa.001

Since the keystore is empty, you should create a passphrase for it. A passphrase -is used to PBE encrypt the actual storage which the keystore uses as back-end. -After you enter a passphrase, the resulting output should be similar to:

-Symbian OS KeyStore Manipulation Tool -Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). 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:\keystore\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, it is c:\keystore\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:

If you try to import a key with the same label, an error will occur as -shown:

-c:\>keytool –label abc –import c:\keystore\data\pkcs8rsa -Symbian OS KeyStore Manipulation Tool -Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. -The given label is invalid, or already present in the keystore. -Error code: KErrAlreadyExist - -

However, this happens because of the attempt to insert the key in a keystore -implementation where the same label already exists. Remember that if you do -not specify the key store implementation to use in a command, the first (index -0) is used by default. You can insert the key with label abc in the keystore -implementation with index 1 (if such an implementation exists), as shown in -the following example:

-c:\>keytool –label abc –store 1 –import c:\keystore\data\pkcs8rsa -Symbian OS KeyStore Manipulation Tool -Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). 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 are identical from the keystore point of view. -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 above procedure might be -lengthy. keytool offers wildcards to solve this problem. -You can 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:\keystore\data. You can do that depending on the actual file -names, with a command similar to:

keytool –import c:\keystore\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. You must, therefore, enter the passphrase for a given -encrypted key.

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

-Listing Keystore -Contents -Removing -Keys -Working with -Multiple Keystore Implementations + + + + + +Importing +Private Keys +

The Symbian key store supports two types of key, DSA keys +and RSA keys. You can use 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).

Suppose the keystore is empty and you want to populate it by importing +private keys which are stored in your Symbian device file system. Start by +importing an RSA private key stored in the file pkcs8rsa.001:

keytool –import c:\keystore\data\pkcs8rsa.001

Since the keystore is empty, you should create a passphrase for it. A passphrase +is used to PBE encrypt the actual storage which the keystore uses as back-end. +After you enter a passphrase, the resulting output should be similar to:

+Symbian KeyStore Manipulation Tool +Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). 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:\keystore\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, it is c:\keystore\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:

If you try to import a key with the same label, an error will occur as +shown:

+c:\>keytool –label abc –import c:\keystore\data\pkcs8rsa +Symbian KeyStore Manipulation Tool +Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. +The given label is invalid, or already present in the keystore. +Error code: KErrAlreadyExist + +

However, this happens because of the attempt to insert the key in a keystore +implementation where the same label already exists. Remember that if you do +not specify the key store implementation to use in a command, the first (index +0) is used by default. You can insert the key with label abc in the keystore +implementation with index 1 (if such an implementation exists), as shown in +the following example:

+c:\>keytool –label abc –store 1 –import c:\keystore\data\pkcs8rsa +Symbian KeyStore Manipulation Tool +Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies). 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 are identical from the keystore point of view. +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 above procedure might be +lengthy. keytool offers wildcards to solve this problem. +You can 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:\keystore\data. You can do that depending on the actual file +names, with a command similar to:

keytool –import c:\keystore\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. You must, therefore, enter the passphrase for a given +encrypted key.

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

+Listing Keystore +Contents +Removing +Keys +Working with +Multiple Keystore Implementations

\ No newline at end of file