diff --git a/man/man3/Makefile.am b/man/man3/Makefile.am index da8ec0ff..b3615f50 100644 --- a/man/man3/Makefile.am +++ b/man/man3/Makefile.am @@ -19,6 +19,7 @@ man3_PODS = \ TPMLIB_RegisterCallbacks.pod \ TPMLIB_SetBufferSize.pod \ TPMLIB_SetDebugFD.pod \ + TPMLIB_SetProfile.pod \ TPMLIB_SetState.pod \ TPMLIB_ValidateState.pod \ TPMLIB_VolatileAll_Store.pod \ @@ -48,6 +49,7 @@ man3_MANS_generated = \ TPMLIB_Process.3 \ TPMLIB_SetDebugFD.3 \ TPMLIB_SetBufferSize.3 \ + TPMLIB_SetProfile.3 \ TPMLIB_SetState.3 \ TPMLIB_RegisterCallbacks.3 \ TPMLIB_ValidateState.3 \ diff --git a/man/man3/TPMLIB_SetProfile.pod b/man/man3/TPMLIB_SetProfile.pod new file mode 100644 index 00000000..7956480b --- /dev/null +++ b/man/man3/TPMLIB_SetProfile.pod @@ -0,0 +1,219 @@ +=head1 NAME + +TPMLIB_SetProfile - Set a profile for a TPM 2 + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B<#include > + +B + +=head1 DESCRIPTION + +B is used to apply one of libtpms's provided profiles +to a TPM 2 when it is started the first time. B must be +called after B and before B. +A profile may only be applied to a TPM 2 and will always fail for a TPM 1.2. + +Once a profile has been set it will be used by the TPM 2 from then on and +the profile will be carried along with the state of the TPM 2 if the state +of the TPM 2 was written using the callback registered with +B. Later attempts to set a different profile +for the same TPM 2 instance using this API call will have no effect. + +Libtpms v0.10 and later support several built-in profiles. The 'null' profile +provides backwards compatibility for libtpms v0.9 and only enables those +algorithm and commands that were available at that version of libtpms. +The default profile enables all currently available commands and algorithms. +Neither one of these profiles allows any modifications by the user. The +'custom' profile is the only one that a user may modify and where the user +may disable any commands and/or algorithms that can be disabled. + +If a NULL pointer is given as a profile then the 'null' profile will be +used and only commands and algorithms of libtpms v0.9 will be enabled. +The state of such a TPM 2 instance will be readable by the current version of +libtpms as well as later versions of libtpms and allow for downgrading +libtpms to version 0.9 from a later version. + +Profiles with the prefix 'default' enable as many algorithms and commands +as possible. The 'default-v1' profile, introduced with libtpms v0.10, allows +to run with libtpms v0.10 and later but will not allow to downgrade to +earlir versions of libtpms, such as v0.9. + +A profile is a JSON map in string format. It must contain the 'Name' +field with the name of a known profile. It may contain a field +'Algorithms' that holds a comma-separated list of algorithms (verbs) to +enable or the field 'Commands' that holds a comma-separated list of ranges +of command codes to enable. + +The following are examples of TPM 2 profiles: + + {"Name":"default-v1"} + + { + "Name":"custom", + "Algorithms":"rsa,rsa-min-size=1024,tdes-min-size=128,hmac,aes,\ + aes-min-size=128,mgf1,keyedhash,xor,sha256,sha384,\ + sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,ecdh,ecdaa,\ + sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,kdf1-sp800-108,\ + ecc,ecc-min-size=192,ecc-nist,ecc-nb,symcipher,camellia,\ + camellia-min-size=128,cmac,ctr,ofb,cbc,cfb,ecb", + "StateFormatLevel":2 + } + +The first profile selects the current default profile along with all +commands and algorithms that are available. +The second profile selects the I profile but restricts the +set of algorithms that the TPM 2 provides to those ones that are listed. +Since 'sha1' and 'tdes' are missing in the list, it disables those algorithms. +Note that the I profile is the only profile that allows customizations +of enabled Algorthms and Commands. + +Only a subset of the implemented algorithms can be disabled. To determine +the list of algorithms that can be disabled, use the list of algorithms +return by I in the +'CanBeDisabled' field. Similarly, only a subset of the implemented commands +can be disabled and I can +be used to determine the list of 'CanBeDisabled' commands. + +Since it is possible to disable algorithms that are mandatory for the +PC client TPM 2 one can create a TPM 2 instance that will cause +applications to fail. Therefore, it is necessary to carefully select which +algorithms to disable following the requirements of applications that will +be used. At the same time the choice of enabled commands is important +so that algorithms that are enabled can actually be used with the set +of enabled commands and applications do not fail unexpectedly because of +disabled commands. Therefore, determining the list of algorithms and +commands to enable and disable is left to the user. + +=head1 StateFormatLevel + +The I field exists in each profile carried by the +state of a TPM 2. The I is an integer that is increased +whenever new TPM 2 commands or algorithms are enabled for profiles. The effect +of this parameter is that a profile with I 'n' will not be +accepted by a libtpms version that does not at least implement +I 'n'. This prevents applications that may have used any newly +enabled algorithms or commands from failing because they try to use them +again with a TPM 2 from a libtpms version that does not support them. + +When the above is applied to a virtual machine environment then this means that +migrating the state of a TPM 2 is only possible to a libtpms version that +implements at least the same StateFormatLevel. Therefore, care must be taken +which profile is chosen so that the profile's StateFormatLevel does not +become the obstacle for migrating the TPM state between different versions +of libtpms. This in turn means that in an environment where older libtpms +versions exist, which may be a target for migration, then the oldest +libtpms version's supported profile should be chosen. If libtpms v0.9 +exists then this should be the 'null' profile, for libtpms v0.10 this can +be the the 'default-v1' profile. + +The following lists the meaning of Is: + +=over 4 + +=item 1: (since v0.10) + +This is reserved for the null profile. Only algorithms +and commands supported by libtpms v0.9 are enabled. To remain compatible +with libtpms v0.9 state format, the null profile will not be written as part +of the state. + +=item 2: (since v0.10) + +This I enabled the writing of the profile as part of the +state. + +=back + +A user may specify the I when using the I profile. +In this case the given I serves as the maximum +I that the given algorithms and commands may require +(e.g., '2' would not allow to enable the command ECC_Encrypt, which +requires '3') or allows to enable key sizes, such as AES-192, when for +example I '4' is given. If I '3' +is given then AES-192 will not be enabled. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +A failure occurred. This may be due to a badly formatted JSON profile, +a missing field in the JSON profile, an unknown verb in the JSON profile, +or an out of memory error. The log file may show the reason for the +failure. + +A TPM 1.2 cannot have a profile applied and will always respond with +this error code. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 EXAMPLE + + #include + + #include + #include + #include + + int main(void) { + TPM_RESULT res; + unsigned char *respbuffer = NULL; + uint32_t resp_size = 0; + uint32_t respbufsize = 0; + unsigned char *command; + uint32_t command_size; + + [...] + + if (TPMLIB_ChooseTPMVersion(TPMLIB_TPM_VERSION_2) != TPM_SUCCESS) { + fprintf(stderr, "Could not choose a TPM 2.\n"); + return 1; + } + + if (TPMLIB_SetProfile(NULL) != TPM_SUCCESS) { + fprintf(stderr, "Could not set the profile.\n"); + return 1; + } + + if (TPMLIB_MainInit() != TPM_SUCCESS) { + fprintf(stderr, "Could not start the TPM.\n"); + return 1; + } + + [...] + /* build TPM command */ + [...] + + res = TPMLIB_Process(&respbuffer, &resp_size, + &respbufsize, + command, command_size); + [...] + + TPMLIB_Terminate(); + + return 0; + } + +=head1 SEE ALSO + +B, B(3), B(3) + +=cut