Kmyth Command Line Tools

Tools

The tools in kmyth depend on the version of TPM on the system. Their interfaces are slightly different, but they provide similar data protections. This wiki is divided into sections based on TPM 1.2 and TPM 2.0.

The three tools built by Kmyth are: kmyth-seal, kmyth-unseal, and kmyth-getkey

Kmyth for TPM 2.0

kmyth-seal (TPM 2.0)

Kmyth-seal is an easy-to-use tool that encrypts a file, backing it by the local machine's TPM; that is, it allows the user to encrypt a file, then TPM-seal the encryption key. It is functionally very similar to tpm_sealdata provided by tpm-tools (albeit using a TPM 2.0 rather than 1.2), but it also provides the user access to the cipher suite chosen to encrypt the file.

$ ./kmyth-seal 

usage: ./kmyth-seal [options] 

options are: 

 -a or --auth_string   String used to create 'authVal' digest. Defaults to empty string (all-zero digest).
 -i or --input         Path to file containing the data to be sealed.
 -o or --output        Destination path for the sealed file. Defaults to <filename>.ski in the CWD.
 -f or --force         Force the overwrite of an existing .ski file when using default output.
 -p or --pcrs_list     List of TPM platform configuration registers (PCRs) to apply to authorization policy.
                       Defaults to no PCRs specified. Encapsulate in quotes (e.g. "0, 1, 2").
 -c or --cipher        Specifies the cipher type to use. Defaults to 'AES/GCM/NoPadding/256'
 -l or --list_ciphers  Lists all valid ciphers and exits.
 -w or --owner_auth    TPM 2.0 storage (owner) hierarchy authorization. Defaults to emptyAuth to match TPM default.
 -v or --verbose       Enable detailed logging.
 -h or --help          Help (displays this usage).

input is required, and output is a strongly recommended option.

For more information about the PCRs, see your vendor's documentation.

The following ciphers are currectly supported by kmyt:

AES/GCM/NoPadding/256 (default)
AES/GCM/NoPadding/192
AES/GCM/NoPadding/128
AES/KeyWrap/RFC3394NoPadding/256
AES/KeyWrap/RFC3394NoPadding/192
AES/KeyWrap/RFC3394NoPadding/128
AES/KeyWrap/RFC5649Padding/256
AES/KeyWrap/RFC5649Padding/192
AES/KeyWrap/RFC5649Padding/128

kmyth-unseal (TPM 2.0)

$ ./kmyth-unseal 

usage: ./kmyth-unseal [options]

options are: 

 -a or --auth_string   String used to create 'authVal' digest. Defaults to empty string (all-zero digest).
 -i or --input         Path to file containing data the to be unsealed
 -o or --output        Destination path for unsealed file. If none given, will attempt to use the original
                       filename read from the .ski file in the local directory. Will not overwrite any
                       existing files unless the 'force' option is selected.
 -f or --force         Force the overwrite of an existing output file
 -s or --stdout        Output unencrypted result to stdout instead of file.
 -w or --owner_auth    TPM 2.0 storage (owner) hierarchy authorization. Defaults to emptyAuth to match TPM default.
 -v or --verbose       Enable detailed logging.
 -h or --help          Help (displays this usage).

input is required, and output OR stdout is required.

kmyth-getkey (TPM 2.0)

$ ./kmyth-getkey 

usage: ./kmyth-getkey [options]

options are:

Client Information --
  -i or --input         Path to file containing the kmyth-sealed client's certificate private key.
  -l or --client        Path to file containing the client's certificate.

Server Information --
  -s or --server        Path to file containing the certificate
                        for the CA that issued the server cert.
  -c or --conn_addr     The ip_address:port for the TLS connection.
  -m or --message       An optional message to send the key server.

Output Parameters --
  -o or --output        Output file path to write the key. If none is selected, key will be sent to stdout.

Sealed Key Parameters --
  -a or --auth_string   String used to create 'authVal' digest. Defaults to empty string (all-zero digest)
  -w or --owner_auth    TPM 2.0 storage (owner) hierarchy authorization. Defaults to emptyAuth to match TPM default.

Misc --
  -v or --verbose       Detailed logging mode to help with debugging.
  -h or --help          Help (displays this usage).

input, client, server, and address are all required.

Kmyth-getkey requires the server provide one of the four following cipher suites:

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

Kmyth for TPM 1.2

kmyth-seal (TPM 1.2)

Kmyth-seal is an easy-to-use tool that encrypts a file, backing it by the local machine's TPM; that is, it allows the user to encrypt a file, then TPM-seal the encryption key. It is functionally very similar to tpm_sealdata provided by tpm-tools, but it also provides the user access to the cipher suite chosen to encrypt the file.

$ kmyth-seal  

usage: kmyth-seal [options] 
options are: 
 -i or --input        : Path to file containing data to be encrypted
 -o or --output       : Ouput file path, if none given will overwrite input file
 -p or --pcrs_list    : List of PCRS, defaults to none. Encapsulate in quotes, e.g. "0, 1, 2"
 -c or --cipher       : Specifies the cipher type to use. Defaults to AES/GCM/NoPadding/256
 -v or --verbose      : Adds print statements to help with debugging
 -h or --help         : help
 -l or --list_ciphers : Lists all valid ciphers and exits.

input is required, and output is a strongly recommended option.

For more information about the the PCRs, see your vendor's documentation.

The following ciphers are currently supported by kmyth:

AES/GCM/NoPadding/256 (default)
AES/GCM/NoPadding/192
AES/GCM/NoPadding/128
AES/KeyWrap/RFC3394NoPadding/256
AES/KeyWrap/RFC3394NoPadding/192
AES/KeyWrap/RFC3394NoPadding/128

kmyth-unseal (TPM 1.2)

$ kmyth-unseal 

usage: kmyth-unseal [options] 
options are: 
 -i or --input    : Path to file containing data to be decrypted
 -o or --output   : Path to output file destination. This or -s must be specified
 -s or --standard : Output decrypted result to standard out
 -v or --verbose  : Adds print statements to help with debuging
 -h or --help     : help

input is required, and output OR standard is required.

kmyth-getkey (TPM 1.2)

$ kmyth-getkey 

usage: kmyth-getkey [options] 
options are: 

 Client Certificate information --
 -i or --input  : Path to file containing the kmyth-sealed client's private authentication key
 -l or --client : Path to file containing the client's certificate

 Server information --
 -s or --server  : Path to file containing the server's certificate
 -a or --address : The ip_address:port for the TLS connection
 -m or --message : An optional message to send the key server

 Output information --
 -o or --output   : Output file path to write the key. If none is selected, key will be sent to stdout

 Misc --
 -v or --verbose : Adds print statements to help with debugging
 -h or --help    : help