TPM_LOADKEY(3)

NAME
TPM_LoadKey, TPM_EvictKey, TPM_CreateWrapKey - Create, load, and remove keys from the TPM chip

LIBRARY
tcpa

SYNOPSIS
#include <tcpa.h>
uint32_t
TPM_LoadKey(uint32_t keyhandle, unsigned char *keyauth, keydata *keyparams, uint32_t *newhandle, FILE *log);
uint32_t
TPM_EvictKey(uint32_t keyhandle, FILE *log);
uint32_t
TPM_CreateWrapKey(uint32_t keyhandle, unsigned char *keyauth, unsigned char *newauth, unsigned char *migauth, keydata *keyparams, keydata *key, FILE *log);

DESCRIPTION
The first two functions allow a program to load and remove keys from the temporary key storage on the TPM chip. The third function allows for creation of new keys by the chip. The benefit of creating keys on the chip is that the private key will never leave the chip unencrypted, and as such will never be compromised by an attacker (except one that has physical access to the chip). Togethers, these functions comprise the key management functions of the TPM chip. All three functions take the log parameter. This is used for diagnostic purposed, and outputs debugging information to the FILE log if non-NULL.

To load a key into the temporary key storage of the TPM chip, use TPM_LoadKey(). You must have three things to use this function. Every key to be loaded was encrypted by some other, parent, key. The root of this is the Storage Root Key. The parent key must already be loaded into the chip, and you need to know the key handle of that parent key. ( The key handle for the SRK key is 0x40000000). This handle is passed in as keyhandle. Second, there is some authorization information (a password) that must be known to use a key. The SHA1 hash of this password is the second parameter keyauth. Finally, you must have the encrypted key itself, which is returned from TPM_CreateWrapKey(). This is passed in as keyparams. The handle of the newly loaded key will be returned in *newhandle.

To remove a key from the temporary storage, use TPM_EvictKey(). This function just takes the handle of the key to be evicted in keyhandle.

The TPM can create a new key with TPM_CreateWrapKey(). This requires a bunch of information. First of all, the key that is to be the parent of this new key must be loaded into the chip. Its handle is passed in as keyhandle. Also, the authorization secret (password as a SHA1 hash) must also be passed into this function to authorize using this key to parent a new key. This secret is keyauth. I'm not sure what migauth is used for. Next comes information about the new key. First is the authorization secret (password as a SHA1 hash) of the new key, passed in as newauth. Next is a bunch of information about what type of key to generate. This is passed in as a keydata structure as parameter keyparams. Finally, the new key is returned (in encrypted form) into *key.

The keydata structure that is passed around by these three functions has the following form:

    typedef struct keydata {
        unsigned char version[4];
        uint16_t keyusage;
        uint32_t keyflags;
        unsigned char authdatausage;
        pubkeydata pub;
        uint32_t privkeylen;
        unsigned char encprivkey[1024];
    } keydata;

Most of these elements of the structure are fairly self-explanatory. version is normally 1.1.0.0. For keyusage, 0x0010 is a signing-only key, and 0x0011 is a storage-only key. The key can only be used for one purpose for security reasons. A value of 0x01 for authdatausage means that the key only requires a password to use it.

This structure also uses the pubkeydata structure:

    typedef struct pubkeydata {
        uint32_t algorithm;
        uint16_t encscheme;
        uint16_t sigscheme;
        uint32_t keybitlen;
        uint32_t numprimes;
        uint32_t expsize;
        unsigned char exponent[3];
        uint32_t keylength;
        unsigned char modulus[256];
        uint32_t pcrinfolen;
        unsigned char pcrinfo[256];
    } pubkeydata;

Common values include:
-   0x00000001 for algorithm means use RSA encryption
-   0x0001 for encscheme means signing, 0x0003 means storage.
-   0x0002 for sigscheme means use RSA / SHA1 for signing, 0x0001 means none (storage key).
-   2048 for keybitlen is the normal key length used.
-   2 for numprimes is required, and means use exactly 2 primes for RSA.
-   0 for expsize means use the default exponent of 65537.
-   0 for pcrinfolen means don't link the key to any values for pcr's.

RETURN VALUES

SEE ALSO
TPM_Transmit(3), TPM_OIAP(3), TPM_GetCapability_Version(3), TPM_TakeOwnership(3), TPM_ReadPubek(3), TPM_Seal(3), TPM_Sign(3)

AUTHORS
Rick Wash <rwash@citi.umich.edu>

BUGS
Doesn't include information about a lot of the different possible values in that structure, and therefore about the various keys that can be created and used. Also, doesn't include how to link a key to pcr's.