Perform cryptographic operations with symmetric keys

After introducing asymmetric keys in the previous pill, it's time to move on to symmetric keys.

Like asymmetric keys, symmetric keys can be used to perform encryption/decryption or signature operations. These two types of operations allow us to address a number of use cases, the most well-known being probably the encryption function that enables Bitlocker (on Windows) and systemd (on Linux) to work.

Now, let's take a closer look at how things work through a series of small examples!

Encryption / Decryption vs. Seal / Unseal

It is necessary to distinguish between encryption and sealing. In one case we will use a key to perform cryptographic operations (e.g. AES or SM4), in the other we will want to protect a secret generally produced outside the TPM.

Encryption / Decryption

tpm2_getcap commands | grep -i encryptdecrypt

Let's start by creating a symmetric key with the following characteristics:

Table: Key attributes

# Note: the key will be stored in the current directory
# with the name `key.tpm`
go run github.com/loicsikidi/tpm-pills/examples/06-pill create
# output: Ordinary key created successfully 🚀

Now, we can perform encryption / decryption:

go run github.com/loicsikidi/tpm-pills/examples/06-pill encrypt --message "Hello TPM Pills!" --output ./blob.enc
# output: Encrypted message saved to ./blob.enc 🚀

go run github.com/loicsikidi/tpm-pills/examples/06-pill decrypt --key ./key.tpm \
--in ./blob.enc
# output: Decrypted "Hello TPM Pills!" successfully 🚀

# clean up
go run github.com/loicsikidi/tpm-pills/examples/06-pill cleanup
rm -f ./key.tpm ./blob.enc

Under the hood, the CLI uses the TPM2_EncryptDecrypt2 command (which is the successor of TPM2_EncryptDecrypt as it adds a security element¹)

rsp, _ := tpm2.EncryptDecrypt2{
	KeyHandle: keyHandle, // reference to the key doing the job

	// if the payload is bigger than TPM's buffer
	// we can use pagination ⬇️
	Message: tpm2.TPM2BMaxBuffer{
		Buffer: block,
	},
	Mode:    mode, // eg. CFB, GCM, etc.
	Decrypt: decrypt, // this is a boolean
	IV: tpm2.TPM2BIV{
		Buffer: iv,
	},
}.Execute(tpm)

Seal / Unseal

Since support for TPM2_EncryptDecrypt and TPM2_EncryptDecrypt2 is not widespread, you will mostly use sealing to encrypt secrets at rest.

$IMAGE

To do this, you have two steps:

1. the seal: TPM2_CreatePrimary or TPM2_Create
2. the unseal: TPM2_Unseal

Data to seal is nothing more and nothing less than a key with the following properties:

Table: Sealed data key attributes

In short, a key that technically can do nothing except return its content via the TPM2_Unseal command.

Let's see what it looks like in code:

# SEAL
createRsp, _ := tpm2.Create{
    ParentHandle: parentHandle,
    InPublic: tpm2.New2B(tpm2.TPMTPublic{
		Type:    tpm2.TPMAlgKeyedHash, // indicates that it's a shared secret
		NameAlg: tpm2.TPMAlgSHA256,
		ObjectAttributes: tpm2.TPMAObject{
			FixedTPM:            true,
			FixedParent:         true,
			UserWithAuth:        true,
			SensitiveDataOrigin: false,  // necessary because the value has been generated outside the TPM
			SignEncrypt:         false,
			Decrypt:             false,
			Restricted:          false,
		},
	}),
	InSensitive: TPM2BSensitiveCreate{
		Sensitive: &TPMSSensitiveCreate{
			Data: NewTPMUSensitiveCreate(&TPM2BSensitiveData{
				Buffer: []byte("VALUE TO SEAL"), // data blob
			}),
		},
	},
}.Execute(tpm)

# UNSEAL
unsealRsp, _ := tpm2.Unseal{
	ItemHandle: keyHandle, // key to unseal's handle
}.Execute(thetpm)

As we can see above, the seal consists of creating a symmetric key by providing it with the value. The TPM via the Primary Seed (i.e. TPM2_CreatePrimary) or the Storage Parent (i.e. TPM2_Create) is able to encrypt the key's content to store it securely.

Please find below a concrete example using the CLI:

go run github.com/loicsikidi/tpm-pills/examples/06-pill seal \
--message "important secret" --output ./sealed_key.tpm
# output: Sealed message saved to ./sealed_key.tpm 🚀

go run github.com/loicsikidi/tpm-pills/examples/06-pill unseal --in ./sealed_key.tpm
# output: Unsealed message: "important secret" 🚀

# clean up
go run github.com/loicsikidi/tpm-pills/examples/06-pill cleanup
rm -f ./sealed_key.tpm

Signature

Here, HMAC³ is used to sign messages, most often for authentication purposes. For example, the S3 authentication protocol relies on this principle (i.e. AWS Signature v4) by sharing a shared secret with the client.

For this use case, this pill will not provide an example, however, here are two repos that show how to implement this in Go:

• aws_hmac
• gcs_tpm

Deep dive: derives key (KDF)

In addition to signing, the HMAC function provides a quite interesting property, that of being able to derive other symmetric keys from a master key.

The idea is quite elegant in that:

• the master key is stored in a secure environment (i.e. TPM)
• the TPM is autonomous to generate the HMAC

The HMAC plays the role of Pseudorandom Function (PRF) to produce a seed that will be used by a Key Derivation Function (KDF) to generate a key with good entropy.

Here's how this applies in a TPM context:

• K: is an HMAC type key that is loaded in the TPM (key handle in the diagram below)
• M: is the data to be signed (data in the diagram below)

The example below shows how to generate an HMAC with a digest produced with SHA-256:

go run github.com/loicsikidi/tpm-pills/examples/06-pill hmac --data "secret"
# output: HMAC result: "bde701bc281f6d5e55ee29b30c08c59fb05425298442b5060238af88305964a0" 🚀

# value is deterministic
go run github.com/loicsikidi/tpm-pills/examples/06-pill hmac --data "secret"
# output: HMAC result: "bde701bc281f6d5e55ee29b30c08c59fb05425298442b5060238af88305964a0" 🚀

# clean up
go run github.com/loicsikidi/tpm-pills/examples/06-pill cleanup

Note: the output is formatted in hexadecimal for clarity but this doubles the payload size. Originally it is 32 bytes, in hex it is therefore 64 bytes.

The key that was produced has the following characteristics this time:

Table: HMAC key attributes

Since HMAC is a signature protocol, this is indeed a prerequisite.

The size of the seed varies depending on the hash function.

Table: HMAC length by hash algorithm

Acknowledgement

You probably noticed that this pill mentions several repos belonging to salrashid123 who is a person whose contributions on TPM usage are invaluable.

Shout-out to him!

Bonus

The file 06-pill/concepts_test.go includes unit tests demonstrating some concepts that were discussed in this pill (e.g. maximum seal size, HMAC sizes, etc.)

Conclusion

In this pill, we introduced different use cases for symmetric keys. The key takeaways are as follows:

• support for symmetric encryption is very limited
• seal/unseal turns out to be the alternative
• HMAC is the first-class citizen algorithm for signing

Nevertheless, some might say "that's nice and all, but where is the authorization layer?". A little patience, this topic will be addressed as soon as the main concepts are mastered, but know that it is possible to set up more or less complex locks. For example, it is possible to:

• ask the user to provide a passphrase to authorize unsealing
• limit the unseal operation only during boot (not after in user-space)
• authorize unsealing if and only if the machine is in a trusted state at boot time (cf. measured boot)

Next Pill...

...we will focus on the two elements that allow referencing a key (the handle and the name) in a TPM.

🚧 TPM Pills is in beta 🚧

• if you encounter problems 🙏 please report them on the tpm-pills issue tracker
• if you think that TPM Pills should cover a specific topic which isn't in the roadmap, let's initiate a discussion

1. TPM2_EncryptDecrypt2 adds the ability to encrypt in transit the content of the data to be encrypted or decrypted. ↩

2. concept defined in pill #4 ↩

3. see the Wikipedia page ↩

4. I'm referring in particular to GCP Workload Identity, AWS STS or AD federated identity credentials ↩