-
Notifications
You must be signed in to change notification settings - Fork 53
Kmyth Tpm1 Details
This page is specifically about the TPM 1.2, older TPMs are not supported by kmyth.
The following must occur in order for kmyth to be used:
* tpm-tools and trousers must be installed
* The TPM has been enabled (via BIOS)
* The tcsd service has been started
* Someone has taken ownership of the TPM. Currently, Kmyth will only work if the SRK is generated using the WKS.
* Access control mechanisms for using the TPM do not prohibit access by Kmyth
Keeping in mind that each section is written from the perspective of using Kmyth to protect a node's CAPK and retrieve a key from a key server, the following provides a little more detail into the processes of the Kmyth tools. None of the components delve into the details of interacting with the TPM, but a high level description of some of the programmatic API can be found in the next section.
- Create the Client Wrapping Key
- Encrypt the Client Authentication Private Key using the Client Wrapping Key and the specified cipher suite
- Create the Storage Key
- Seal the Client Wrapping Key using the Storage Key
- Clear the Client Wrapping Key from memory within kmyth-seal
- Clear the Client Authentication Private key from memory within kmyth-seal
- Record the encrypted Storage Key, the cipher suite used by the Client Wrapping Key, the encrypted Client Wrapping Key, and the encrypted CAPK in a file
The files containing the recorded information are known as .ski files, and their format is described below. The format of the .ski files does change between the TPM 1.2 and TPM 2.0.
- Read and parse the .ski file
- Unseal the Client Wrapping Key
- Decrypt the Client Authentication Private Key
- Clear the Client Wrapping Key from memory within kmyth-unseal
- Output the Client Authentication Private Key (to a file to stdout)
- Clear the Client Authentication Private key from memory within kmyth-unseal
- Use the kmyth-unseal process to access the Client Authentication Private Key
- Use the Client Authentication Private Key to establish a TLS connection with the key server
- Clear Client Authentication Private Key from memory within kmyth-getkey
- Retrieve the Operational Key from the key server
- Close the TLS connection
- Output the Operational Key (to file or stdout)
- Clear the Operational Key from memory within kmyth-getkey
Kmyth provides access to the TPM without requiring detailed knowledge of the TPM. There is a programmatic API for Kmyth that exposes the core functionality of the TPM but handles many of the underlying details. These tools use TrouSerS aka TSS to communicate with the TPM. Below are some examples taken from the source code. Kmyth uses Doxygen to produce more complete code docs when the source is built.
int initTPM(attributesTPM * attr, unsigned char *tpm_password, size_t tpm_password_size, bool verbose)
This function initializes the TPM by creating the required context, and it is needed for any/all calls to the TPM.
There are other tools available for creating objects:
int create_TPM_sk(attributesTPM * attr, skTPM * storage_key, unsigned char *sk_password, size_t sk_password_size, bool verbose)
int create_TPM_dataObj(attributesTPM * attr, dataTPM * tpm_data_obj, int *pcrs, unsigned char *data_password, size_t data_password_size, bool verbose)
These tools create objects used by the TPM. In the case of these two, they create the storage key and data object to be encrypted, and they handle the details of object creation for the developer.
More example tools are used for memory management:
int freeTPM(attributesTPM * attr, bool verbose)
int freeTPM_sk(attributesTPM * attr, skTPM * storage_key, bool verbose)
int freeTPM_data(attributesTPM * attr, dataTPM * tpm_data_obj, bool verbose)
Each of these frees memory allocated by the TSS for use in conjunction with the TPM.
There are more helper functions, but these are not necessary for a user to learn in order to use the programmatic API. Kmyth ships with a couple key functions that allow a developer to use the TPM in a straightforward fashion.
int kmyth_seal_data(unsigned char *data, size_t data_size,
int *pcrs,
cipher_t cipher,
unsigned char **enc_data, size_t * enc_data_size,
unsigned char **sealed_key, size_t * sealed_key_size,
unsigned char **storage_key_blob, size_t * storage_key_blob_size,
char *tpm_password, size_t tpm_password_size,
char *sk_password, size_t sk_password_size,
char *data_password, size_t data_password_size,
bool verbose);
The kmyth_seal_data function takes in the required information and produces encrypted/sealed data for the user. A developer using this function does not need to implement any TPM-specific code themselves. The function handles the TPM calls internally.
int kmyth_unseal_data(cipher_t cipher,
unsigned char *storage_key_blob, size_t storage_key_blob_size,
unsigned char *sealed_key_blob, size_t sealed_key_blob_size,
unsigned char *enc_data, size_t enc_data_size,
char *tpm_password, size_t tpm_password_size,
char *sk_password, size_t sk_password_size,
char *data_password, size_t data_password_size,
unsigned char **plain_text_data, size_t * plain_text_data_size,
bool verbose);
The kmyth_unseal_data function handles the TPM calls for the developer as well. It requires some knowledge of the various components needed by the TPM; however, kmyth also ships with the kmyth_read_file which handles the parsing and the call to kmyth_unseal_data for the developer.
int kmyth_read_file(char *input_path,
char *tpm_password, size_t tpm_password_len,
char *sk_password, size_t sk_password_len,
char *data_password, size_t data_password_len,
unsigned char **data, size_t * data_len,
bool verbose);
The output of the kmyth_read_file allows a developer to read a .ski file and produce the original, plaintext data in memory for use.
The .ski files created by TPM 1.2 have a slightly different format than those created by TPM 2.0. The structure was inspired by the tpm-tools file structure.
-----STORAGE KEY-----
ACgAAAARAAAADAEAAAABAAMAAQAAAAwAAAgAAAAAAgAAAAAAAAAAAAABALWnlXyw
s++y3BLunvbAbXZFg7saJGC6fkk3ye2FfgPfg8GY2TmvDZM5MyJv54NKK++a4Veo
2HcyNOIJmr2CLdYTFw1ktXVsKSdXVJacHkvZxEHYw7fsDUz1VPH2XgC1iFx+UzHm
G8lbd3ODOfmMHaJ+Lc8DTzkjlQjJfyTZ3EgeAx8lvmSuffNzYApBb5pzAgHqBSZx
DSM2YF6F9APxdxjS9JhyUz168AaQaTCG+JcSNiIEjgTAaVCa1XVC/LtCwSp+0Qrm
Zjsvpdp53oYpZsz9Hp3YJXOj1yyPbIsseDrZbpwB4RW2KQDBk+LLrzyr694bYpza
y/ZkdoJtcZddgWsAAAEA0lUu8jxp98LAJ+kn8u1HSsYLBNX4tNnSCUK5x7LZRCw3
YLDHBx4A8of2yyC4ezWqJo8xOZYFyDA4lznb9uKN/+wvW54r4W+6/vAJR72/Kh2c
GwoVg3EIWUHZGZ4nHyiWE0LL1d9axw5OxbM57baAxI0B5UcUFd5oLW0A1gRg5lmy
apo5WDsJpGPRsROOc0R/1xpno73M9isIC0mLs250+zqk5wL8kqVzD6MHqLi3X2H1
4Cmo5cP1SRYqBTmLqNPRbQwirHi+LeiR/t7nV1t6tl6fDkC0ZePbFeOnNihZ/rjm
cd8756v/JmBxCHXLceM5ipqo48xoLvmq5OCcABvAaA==
-----CIPHER SUITE-----
AES-KeyWrap256
-----SYM KEY-----
AQEAAAAAAAAAAAEAa6kkLnmciuTfu1noab08DaprJYkA7IYHAGeQjXogSWpPo/zC
wtwqBBFG63tERpD+NU11+XWT1+sGKTzRsFW0gLx40UVWiuxZ3IFA4fJYfIGhrUk5
j7rZdGOdi5tiHQWJepXD4GQLrAoLtU+2vw9Eq5Sx1JV+xrpcG1fQqyERY4+wKr2m
YyYrB0Qlb1uUO8udGQaFAIiSXSsvXkBTa88xKYrirBAz1OeGEaZU3UcbJblskaLC
h+m3XhEXOtG+9vpr3e1MWaGR59a5djqM0JbpBPygem+z7t1wGDWCK/0f49XI4fnn
HX8DHK1cbS9jRuYweknfd08RFsav/HMHzZuxdg==
-----ENC DATA-----
TQuWZHKTdiTHoefSZJzl5r8D6P1dBEhm5s0fnA6f+JwX0CXgXeyAZTOzc3G7COu+
gaTlKL3DRiKx07KRszJG+wgmSJ1+EiH8RcuxdacLMvVG4zHnJjajAeLIkHzqGLDe
s8UQsCuYD8kBUB7yAeMcRF5n7IFsRiWP8+r1OyIQ48/M8cwM+tZ1txQeMDF4M+BL
R3ye6Kdl9FBgYjnqZXhXdrhB6hJLv35esf76tCrmIXgraIbfi3CBdFNjjrvBIqSP
UZLFm/J2tycx6sAHFDqAmMKGYcPideNwx+DjVHoeUQ3wcv1su2ey5QphAoeeFTVh
YMHPV23lthkcsS6ZvESNZDFCyorV6b3HAEg3xHY4d8lpwJdmf7FtsSv3jI9dwH6X
pTsqeAhNAL5aQjgPKei9nJzraD9gr03C
-----FILE END-----
- STORAGE KEY contains the encrypted storage key.
- CIPHER SUITE specifies the algorithm used to wrap the encrypted data.
- SYM KEY contains the TPM sealed CWK, which has been encrypted with the SK.
- ENC DATA contains the contents of the file (CAPK) encrypted with the CWK.
- FILE END designates the end of a .ski file.