[PATCH 11/23] TPMLIB: Put banner comments on public TPM library functions

David Howells
2018-08-21T19:18:49Z

Put banner comments on public TPM library functions and, if necessary, rename
the arguments to make them more obvious.

Signed-off-by: David Howells <dhowells@redhat.com>
---

drivers/char/tpm/tpm-library.c | 126 ++++++++++++++++++++++++++++------------
include/linux/tpm.h | 19 ++++++
2 files changed, 105 insertions(+), 40 deletions(-)

diff --git a/drivers/char/tpm/tpm-library.c b/drivers/char/tpm/tpm-library.c
index 41fe4247a4c8..7d1f55413f02 100644
--- a/drivers/char/tpm/tpm-library.c
+++ b/drivers/char/tpm/tpm-library.c
@@ -66,8 +66,17 @@ static int TSS_sha1(const unsigned char *data, unsigned int datalen,
return ret;
}

-static int TSS_rawhmac(unsigned char *digest, const unsigned char *key,
- unsigned int keylen, ...)
+/**
+ * TSS_rawhmac - Generate a HMAC(SHA1) from raw data
+ * @digest: Result buffer - must be SHA1_DIGEST_SIZE in size
+ * @key: The key to use in the HMAC generation
+ * @keylen: The size of @key
+ * @...: Pairs of size and pointer of data elements to load into hmac
+ * @0,0: Terminator
+ */
+static int TSS_rawhmac(unsigned char *digest,
+ const unsigned char *key, unsigned keylen,
+ ...)
{
struct tpm_sdesc *sdesc;
va_list argp;
@@ -110,7 +119,17 @@ out:
return ret;
}

-/*
+/**
+ * TSS_authhmac - Calculate authorisation info to send to TPM
+ * @digest: Result buffer - must be SHA1_DIGEST_SIZE in size
+ * @key: The key to use in the HMAC generation
+ * @keylen: The size of @key
+ * @h1: Even nonce
+ * @h2: Odd nonce
+ * @h3: Continuation flag
+ * @...: Pairs of size and pointer of data elements to load into hash
+ * @0,0: Terminator
+ *
* calculate authorization info fields to send to TPM
*/
static int TSS_authhmac(unsigned char *digest, const unsigned char *key,
@@ -378,8 +397,8 @@ static int tpm_send_dump(struct tpm_chip *chip,
*/
static int tpm_create_osap(struct tpm_chip *chip,
struct tpm_buf *tb, struct tpm_osapsess *s,
- const unsigned char *key, uint16_t type,
- uint32_t handle)
+ const unsigned char *keyauth,
+ enum tpm_entity_type keytype, uint32_t keyhandle)
{
unsigned char enonce[TPM_NONCE_SIZE];
unsigned char ononce[TPM_NONCE_SIZE];
@@ -393,8 +412,8 @@ static int tpm_create_osap(struct tpm_chip *chip,
store16(tb, TPM_TAG_RQU_COMMAND);
store32(tb, TPM_OSAP_SIZE);
store32(tb, TPM_ORD_OSAP);
- store16(tb, type);
- store32(tb, handle);
+ store16(tb, keytype);
+ store32(tb, keyhandle);
storebytes(tb, ononce, TPM_NONCE_SIZE);

ret = tpm_send_dump(chip, tb->data, MAX_BUF_SIZE,
@@ -407,7 +426,7 @@ static int tpm_create_osap(struct tpm_chip *chip,
TPM_NONCE_SIZE);
memcpy(enonce, &(tb->data[TPM_DATA_OFFSET + sizeof(uint32_t) +
TPM_NONCE_SIZE]), TPM_NONCE_SIZE);
- return TSS_rawhmac(s->secret, key, SHA1_DIGEST_SIZE,
+ return TSS_rawhmac(s->secret, keyauth, SHA1_DIGEST_SIZE,
TPM_NONCE_SIZE, enonce,
TPM_NONCE_SIZE, ononce,
0, 0);
@@ -444,15 +463,33 @@ struct tpm_digests {
unsigned char nonceodd[TPM_NONCE_SIZE];
};

-/*
- * Have the TPM seal(encrypt) the trusted key, possibly based on
- * Platform Configuration Registers (PCRs). AUTH1 for sealing key.
+/**
+ * tpm_seal - Encrypt one key according to another plus PCR state
+ * @chip: The chip to use
+ * @tb: Large scratch buffer for I/O
+ * @keytype: Type of entity attached to @keyhandle
+ * @keyhandle: TPM-resident key used to encrypt
+ * @keyauth: 'Password' to use the key.
+ * @rawdata: Data to be encrypted
+ * @rawlen: Length of @rawdata
+ * @encbuffer: Buffer to hold the encrypted data (max SHA1_DIGEST_SIZE)
+ * @_enclen: Where to place the size of the encrypted data
+ * @encauth: 'Password' to use to encrypt authorisation key
+ * @pcrinfo: Information on PCR register values to seal to
+ * @pcrinfosize: size of @pcrinfo
+ *
+ * Have the TPM seal (encrypt) the data in the data buffer. The encryption is
+ * based on a key already resident in the TPM and may also include the state of
+ * one or more Platform Configuration Registers (PCRs).
+ *
+ * AUTH1 is used for sealing key.
*/
-int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
+int tpm_seal(struct tpm_chip *chip,
+ struct tpm_buf *tb, enum tpm_entity_type keytype,
uint32_t keyhandle, const unsigned char *keyauth,
- const unsigned char *data, uint32_t datalen,
- unsigned char *blob, uint32_t *bloblen,
- const unsigned char *blobauth,
+ const unsigned char *rawdata, uint32_t rawlen,
+ unsigned char *encbuffer, uint32_t *_enclen,
+ const unsigned char *encauth,
const unsigned char *pcrinfo, uint32_t pcrinfosize)
{
struct tpm_osapsess sess;
@@ -489,13 +526,13 @@ int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
if (ret != TPM_NONCE_SIZE)
goto out;
ordinal = htonl(TPM_ORD_SEAL);
- datsize = htonl(datalen);
+ datsize = htonl(rawlen);
pcrsize = htonl(pcrinfosize);
cont = 0;

/* encrypt data authorization key */
for (i = 0; i < SHA1_DIGEST_SIZE; ++i)
- td->encauth[i] = td->xorhash[i] ^ blobauth[i];
+ td->encauth[i] = td->xorhash[i] ^ encauth[i];

/* calculate authorization HMAC value */
if (pcrinfosize == 0) {
@@ -506,7 +543,7 @@ int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
SHA1_DIGEST_SIZE, td->encauth,
sizeof(uint32_t), &pcrsize,
sizeof(uint32_t), &datsize,
- datalen, data,
+ rawlen, rawdata,
0, 0);
} else {
/* pcr info specified */
@@ -517,7 +554,7 @@ int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
sizeof(uint32_t), &pcrsize,
pcrinfosize, pcrinfo,
sizeof(uint32_t), &datsize,
- datalen, data,
+ rawlen, rawdata,
0, 0);
}
if (ret < 0)
@@ -526,14 +563,14 @@ int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
/* build and send the TPM request packet */
INIT_BUF(tb);
store16(tb, TPM_TAG_RQU_AUTH1_COMMAND);
- store32(tb, TPM_SEAL_SIZE + pcrinfosize + datalen);
+ store32(tb, TPM_SEAL_SIZE + pcrinfosize + rawlen);
store32(tb, TPM_ORD_SEAL);
store32(tb, keyhandle);
storebytes(tb, td->encauth, SHA1_DIGEST_SIZE);
store32(tb, pcrinfosize);
storebytes(tb, pcrinfo, pcrinfosize);
- store32(tb, datalen);
- storebytes(tb, data, datalen);
+ store32(tb, rawlen);
+ storebytes(tb, rawdata, rawlen);
store32(tb, sess.handle);
storebytes(tb, td->nonceodd, TPM_NONCE_SIZE);
store8(tb, cont);
@@ -544,7 +581,7 @@ int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
if (ret < 0)
goto out;

- /* calculate the size of the returned Blob */
+ /* calculate the size of the returned encrypted data */
sealinfosize = LOAD32(tb->data, TPM_DATA_OFFSET + sizeof(uint32_t));
encdatasize = LOAD32(tb->data, TPM_DATA_OFFSET + sizeof(uint32_t) +
sizeof(uint32_t) + sealinfosize);
@@ -557,10 +594,10 @@ int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
storedsize, TPM_DATA_OFFSET,
0, 0);

- /* copy the returned blob to caller */
+ /* copy the encrypted data to caller's buffer */
if (!ret) {
- memcpy(blob, tb->data + TPM_DATA_OFFSET, storedsize);
- *bloblen = storedsize;
+ memcpy(encbuffer, tb->data + TPM_DATA_OFFSET, storedsize);
+ *_enclen = storedsize;
}
out:
kfree(td);
@@ -568,14 +605,25 @@ out:
}
EXPORT_SYMBOL_GPL(tpm_seal);

-/*
+/**
+ * tpm_unseal - Encrypt one key according to another plus PCR state
+ * @chip: The chip to use
+ * @tb: Large scratch buffer for I/O
+ * @keyhandle: TPM-resident key used to decrypt
+ * @keyauth: HMAC key
+ * @encdata: Data to be decrypted
+ * @enclen: Length of @encdata
+ * @decauth: Data to use to decrypt the authorisation key
+ * @rawbuffer: Buffer to hold the decrypted data (max SHA1_DIGEST_SIZE)
+ * @_rawlen: Where to place the size of the decrypted data
+ *
* use the AUTH2_COMMAND form of unseal, to authorize both key and blob
*/
int tpm_unseal(struct tpm_chip *chip, struct tpm_buf *tb,
uint32_t keyhandle, const unsigned char *keyauth,
- const unsigned char *blob, int bloblen,
- const unsigned char *blobauth,
- unsigned char *data, unsigned int *datalen)
+ const unsigned char *encdata, int enclen,
+ const unsigned char *decauth,
+ unsigned char *rawbuffer, unsigned int *_rawlen)
{
unsigned char nonceodd[TPM_NONCE_SIZE];
unsigned char enonce1[TPM_NONCE_SIZE];
@@ -611,14 +659,14 @@ int tpm_unseal(struct tpm_chip *chip, struct tpm_buf *tb,
ret = TSS_authhmac(authdata1, keyauth, TPM_NONCE_SIZE,
enonce1, nonceodd, cont,
sizeof(uint32_t), &ordinal,
- bloblen, blob,
+ enclen, encdata,
0, 0);
if (ret < 0)
return ret;
- ret = TSS_authhmac(authdata2, blobauth, TPM_NONCE_SIZE,
+ ret = TSS_authhmac(authdata2, decauth, TPM_NONCE_SIZE,
enonce2, nonceodd, cont,
sizeof(uint32_t), &ordinal,
- bloblen, blob,
+ enclen, encdata,
0, 0);
if (ret < 0)
return ret;
@@ -626,10 +674,10 @@ int tpm_unseal(struct tpm_chip *chip, struct tpm_buf *tb,
/* build and send TPM request packet */
INIT_BUF(tb);
store16(tb, TPM_TAG_RQU_AUTH2_COMMAND);
- store32(tb, TPM_UNSEAL_SIZE + bloblen);
+ store32(tb, TPM_UNSEAL_SIZE + enclen);
store32(tb, TPM_ORD_UNSEAL);
store32(tb, keyhandle);
- storebytes(tb, blob, bloblen);
+ storebytes(tb, encdata, enclen);
store32(tb, authhandle1);
storebytes(tb, nonceodd, TPM_NONCE_SIZE);
store8(tb, cont);
@@ -646,18 +694,18 @@ int tpm_unseal(struct tpm_chip *chip, struct tpm_buf *tb,
return ret;
}

- *datalen = LOAD32(tb->data, TPM_DATA_OFFSET);
+ *_rawlen = LOAD32(tb->data, TPM_DATA_OFFSET);
ret = TSS_checkhmac2(tb->data, ordinal, nonceodd,
keyauth, SHA1_DIGEST_SIZE,
- blobauth, SHA1_DIGEST_SIZE,
+ decauth, SHA1_DIGEST_SIZE,
sizeof(uint32_t), TPM_DATA_OFFSET,
- *datalen, TPM_DATA_OFFSET + sizeof(uint32_t),
+ *_rawlen, TPM_DATA_OFFSET + sizeof(uint32_t),
0, 0);
if (ret < 0) {
pr_info("TSS_checkhmac2 failed (%d)\n", ret);
return ret;
}
- memcpy(data, tb->data + TPM_DATA_OFFSET + sizeof(uint32_t), *datalen);
+ memcpy(rawbuffer, tb->data + TPM_DATA_OFFSET + sizeof(uint32_t), *_rawlen);
return 0;
}
EXPORT_SYMBOL_GPL(tpm_unseal);
diff --git a/include/linux/tpm.h b/include/linux/tpm.h
index b08539920f76..cbd13e03a869 100644
--- a/include/linux/tpm.h
+++ b/include/linux/tpm.h
@@ -93,6 +93,22 @@ static inline int tpm_get_random(struct tpm_chip *chip, u8 *data, size_t max) {
#define TPM_RETURN_OFFSET 6
#define TPM_DATA_OFFSET 10

+enum tpm_entity_type {
+ TPM_ET_KEYHANDLE = 0x01,
+ TPM_ET_OWNER = 0x02,
+ TPM_ET_DATA = 0x03,
+ TPM_ET_SRK = 0x04,
+ TPM_ET_KEY = 0x05,
+ TPM_ET_REVOKE = 0x06,
+ TPM_ET_DEL_OWNER_BLOB = 0x07,
+ TPM_ET_DEL_ROW = 0x08,
+ TPM_ET_DEL_KEY_BLOB = 0x09,
+ TPM_ET_COUNTER = 0x0a,
+ TPM_ET_NV = 0x0b,
+ TPM_ET_OPERATOR = 0x0c,
+ TPM_ET_RESERVED_HANDLE = 0x40,
+};
+
struct tpm_buf {
int len;
unsigned char data[MAX_BUF_SIZE];
@@ -103,7 +119,8 @@ struct tpm_buf {
extern int tpm_library_use(void);
extern void tpm_library_unuse(void);

-extern int tpm_seal(struct tpm_chip *chip, struct tpm_buf *tb, uint16_t keytype,
+extern int tpm_seal(struct tpm_chip *chip,
+ struct tpm_buf *tb, enum tpm_entity_type keytype,
uint32_t keyhandle, const unsigned char *keyauth,
const unsigned char *data, uint32_t datalen,
unsigned char *blob, uint32_t *bloblen,