tpm2-pytss

https://tpm2-pytss.readthedocs.io/en/latest/
Admin
tpm2-pytss is a Python API for accessing TPM 2.0 devices, providing bindings to tpm2-tss libraries...
Tokens:175,474
Snippets:846
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install tpm2-pytss via PyPi or Git

Source: https://tpm2-pytss.readthedocs.io/en/latest/_sources/install.rst.txt

Commands to install the package directly from PyPi or by cloning the repository for an editable installation.

```console
$ python3 -m pip install tpm2-pytss
```

```console
$ git clone --depth 1 https://github.com/tpm2-software/tpm2-pytss
$ cd tpm2-pytss
$ python3 -m pip install -e .
```

--------------------------------

### Install Native Dependencies via Package Manager

Source: https://tpm2-pytss.readthedocs.io/en/latest/_sources/install.rst.txt

Commands to install required development libraries on Ubuntu and Fedora systems.

```bash
apt-get update
apt-get install libtss2-dev
```

```bash
dnf update
dnf install tpm2-tss-devel
```

--------------------------------

### Hex string representation example

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/types.html

Demonstrates the expected output format for the __str__ method.

```python
bytes(tpm2b_type).hex()
```

--------------------------------

### MAC Start Implementation

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Initializes a MAC sequence using the TPM2_MAC_Start command. Requires ESAPI v4.0.0 or higher.

```python
if not _lib_version_atleast("tss2-esys", "4.0.0"):
    raise NotImplementedError("MAC api not supported below ESAPI v4")

_check_handle_type(handle, "handle")

_check_handle_type(session1, "session1")
_check_handle_type(session2, "session2")
_check_handle_type(session3, "session3")

_check_friendly_int(hash_alg, "hash_alg", TPM2_ALG)

if auth is None:
    auth = TPM2B_AUTH()

auth_cdata = _get_cdata(auth, TPM2B_AUTH, "auth")

sequence_handle = ffi.new("ESYS_TR *")
_chkrc(
    lib.Esys_MAC_Start(
        self._ctx,
        handle,
        session1,
        session2,
        session3,
        auth_cdata,
        hash_alg,
        sequence_handle,
    )
)

return ESYS_TR(sequence_handle[0], ectx=self)
```

--------------------------------

### Install dependencies and run tests

Source: https://tpm2-pytss.readthedocs.io/en/latest/_sources/testing.rst.txt

Installs the package in editable mode with development dependencies and executes the test suite using pytest.

```console
$ pip install -e .[dev]
$ pytest -n$(nproc) -v test
```

--------------------------------

### Start MAC Sequence

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Initializes a MAC sequence using the TPM2_MAC_Start command.

```python
    def mac_start(
        self,
        handle: ESYS_TR,
        auth: Union[TPM2B_AUTH, bytes, str],
        hash_alg: TPM2_ALG,
        session1: ESYS_TR = ESYS_TR.PASSWORD,
        session2: ESYS_TR = ESYS_TR.NONE,
        session3: ESYS_TR = ESYS_TR.NONE,
    ) -> ESYS_TR:
        """Invoke the TPM2_MAC_Start command.

        This function invokes the TPM2_MAC_Start command in a one-call
        variant. This means the function will block until the TPM response is
        available.

```

--------------------------------

### Hash Sequence Start Implementation

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Invokes the TPM2_HashSequenceStart command to begin a hash sequence operation.

```python
_check_handle_type(session1, "session1")
_check_handle_type(session2, "session2")
_check_handle_type(session3, "session3")

_check_friendly_int(hash_alg, "hash_alg", TPM2_ALG)

if auth is None:
    auth = TPM2B_AUTH()

auth_cdata = _get_cdata(auth, TPM2B_AUTH, "auth")

sequence_handle = ffi.new("ESYS_TR *")
_chkrc(
    lib.Esys_HashSequenceStart(
        self._ctx,
        session1,
        session2,
        session3,
        auth_cdata,
        hash_alg,
        sequence_handle,
    )
)

return ESYS_TR(sequence_handle[0], ectx=self)
```

--------------------------------

### Field Upgrade Start Implementation

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Internal implementation for the FieldUpgradeStart command, handling data conversion and C library invocation.

```python
_check_handle_type(authorization, "authorization")
_check_handle_type(key_handle, "key_handle")
fu_digest_cdata = _get_cdata(fu_digest, TPM2B_DIGEST, "fu_digest")
manifest_signature_cdata = _get_cdata(
    manifest_signature, TPMT_SIGNATURE, "manifest_signature"
)

_check_handle_type(session1, "session1")
_check_handle_type(session2, "session2")
_check_handle_type(session3, "session3")

_chkrc(
    lib.Esys_FieldUpgradeStart(
        self._ctx,
        authorization,
        key_handle,
        session1,
        session2,
        session3,
        fu_digest_cdata,
        manifest_signature_cdata,
    )
)
```

--------------------------------

### Start HMAC Sequence

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Initializes an HMAC sequence using the TPM2_HMAC_Start command.

```python
    def hmac_start(
        self,
        handle: ESYS_TR,
        auth: Union[TPM2B_AUTH, bytes, str],
        hash_alg: TPM2_ALG,
        session1: ESYS_TR = ESYS_TR.PASSWORD,
        session2: ESYS_TR = ESYS_TR.NONE,
        session3: ESYS_TR = ESYS_TR.NONE,
    ) -> ESYS_TR:
        """Invoke the TPM2_HMAC_Start command.

        This function invokes the TPM2_HMAC_Start command in a one-call
        variant. This means the function will block until the TPM response is
        available.

        Args:
            handle (ESYS_TR): Handle of an HMAC key.
            auth (Union[TPM2B_AUTH, bytes, str]): Authorization value for subsequent use of the sequence.
            hash_alg (TPM2_ALG): The hash algorithm to use for the HMAC.
            session1 (ESYS_TR): A session for securing the TPM command (optional). Defaults to ESYS_TR.PASSWORD.
            session2 (ESYS_TR): A session for securing the TPM command (optional). Defaults to ESYS_TR.NONE.
            session3 (ESYS_TR): A session for securing the TPM command (optional). Defaults to ESYS_TR.NONE.

        Raises:
            TypeError: If a parameter is not of an expected type.
            ValueError: If a parameter is not of an expected value.
            TSS2_Exception: Any of the various TSS2_RC's the lower layers can return.

        Returns:
            An ESYS_TR handle of ESYS resource for TPMI_DH_OBJECT.

        C Function: Esys_HMAC_Start

        TPM Command: TPM2_HMAC_Start
        """

        _check_handle_type(handle, "handle")

        _check_handle_type(session1, "session1")
        _check_handle_type(session2, "session2")
        _check_handle_type(session3, "session3")

        _check_friendly_int(hash_alg, "hash_alg", TPM2_ALG)

        if auth is None:
            auth = TPM2B_AUTH()

        auth_cdata = _get_cdata(auth, TPM2B_AUTH, "auth")

        sequence_handle = ffi.new("ESYS_TR *")
        _chkrc(
            lib.Esys_HMAC_Start(
                self._ctx,
                handle,
                session1,
                session2,
                session3,
                auth_cdata,
                hash_alg,
                sequence_handle,
            )
        )

        return ESYS_TR(sequence_handle[0], ectx=self)
```

--------------------------------

### Field Upgrade Start Method Definition

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Method signature and docstring for initiating a field upgrade process.

```python
def field_upgrade_start(
    self,
    key_handle: ESYS_TR,
    fu_digest: Union[TPM2B_DIGEST, bytes, str],
    manifest_signature: TPMT_SIGNATURE,
    authorization: ESYS_TR = ESYS_TR.PLATFORM,
    session1: ESYS_TR = ESYS_TR.PASSWORD,
    session2: ESYS_TR = ESYS_TR.NONE,
    session3: ESYS_TR = ESYS_TR.NONE,
) -> None:
```

--------------------------------

### Get Policy Description

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/policy.html

Retrieves the policy description as bytes.

```python
    @property
    def description(self) -> bytes:
        """bytes: The policy description."""
        size = ffi.new("size_t *")
        _chkrc(lib.Tss2_PolicyGetDescription(self._ctx, ffi.NULL, size))

        desc = ffi.new("uint8_t[]", size[0])
        _chkrc(lib.Tss2_PolicyGetDescription(self._ctx, desc, size))
        return ffi.string(desc, size[0])
```

--------------------------------

### Start an Auth Session

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Invokes the TPM2_StartAuthSession command to initialize a session. This is a blocking call that returns an ESYS_TR handle.

```python
_check_handle_type(tpm_key, "tpm_key")
_check_handle_type(bind, "bind")
_check_handle_type(session1, "session1")
_check_handle_type(session2, "session2")
_check_handle_type(session3, "session3")

_check_friendly_int(session_type, "session_type", TPM2_SE)
if isinstance(auth_hash, str):
    auth_hash = TPM2_ALG.parse(auth_hash)
_check_friendly_int(auth_hash, "auth_hash", TPM2_ALG)

nonce_caller_cdata = _get_cdata(
    nonce_caller, TPM2B_NONCE, "nonce_caller", allow_none=True
)

if isinstance(symmetric, str):
    symmetric = TPMT_SYM_DEF.parse(symmetric)
elif symmetric is None:
    symmetric = TPMT_SYM_DEF(algorithm=TPM2_ALG.NULL)
symmetric_cdata = _get_cdata(symmetric, TPMT_SYM_DEF, "symmetric")

session_handle = ffi.new("ESYS_TR *")
_chkrc(
    lib.Esys_StartAuthSession(
        self._ctx,
        tpm_key,
        bind,
        session1,
        session2,
        session3,
        nonce_caller_cdata,
        session_type,
        symmetric_cdata,
        auth_hash,
        session_handle,
    )
)

return ESYS_TR(session_handle[0], ectx=self)
```

--------------------------------

### Constructing TPMT_PUBLIC objects

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/types.html

Examples of using the parse method to create TPMT_PUBLIC structures with different algorithm and attribute configurations.

```python
TPMT_PUBLIC.parse(
    "ecc:ecdh-sha384",
    objectAttributes=TPMA_OBJECT.DEFAULT_TPM2_TOOLS_CREATEPRIMARY_ATTRS)

TPMT_PUBLIC.parse(
    alg="xor:sha512",
    nameAlg="sha256",
    authPolicy=b'\xc5\x81sS\xf2\x9bc\x87r\xdf\x01\xd3\xbaowM\x96Q\xaf\x1a\xeeKEO\x82\xfeV\xf3\x13^[\x87')
```

--------------------------------

### Example ImportError for Missing Libraries

Source: https://tpm2-pytss.readthedocs.io/en/latest/_sources/install.rst.txt

A common error message encountered when shared libraries are not correctly configured in the system path.

```text
ImportError: libtss2-esys.so.0: cannot open shared object file: No such file or directory
```

--------------------------------

### startup(startup_type)

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Invokes the TPM2_Startup command to initialize the TPM.

```APIDOC
## startup

### Description
Invokes the TPM2_Startup command in a blocking one-call variant.

### Parameters
- **startup_type** (TPM2_SU) - Required - The startup type, either TPM2_SU_CLEAR or TPM2_SU_STATE.
```

--------------------------------

### Provisioning the FAPI

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/FAPI.html

Initializes the keystore and creates TPM objects. Requires hierarchy passwords and handles existing provisioning states.

```python
def provision(
    self,
    auth_value_eh: Optional[Union[bytes, str]] = None,
    auth_value_sh: Optional[Union[bytes, str]] = None,
    auth_value_lockout: Optional[Union[bytes, str]] = None,
    is_provisioned_ok: bool = True,
) -> bool:
    """Provision the Feature API. Creates the keystore and creates some TPM
    objects. See also config file `/etc/tpm2-tss/fapi-config.json`.

    Args:
        auth_value_eh (bytes or str): Endorsement Hierarchy password. Defaults to None.
        auth_value_sh (bytes or str): Storage/Owner Hierarchy password. Defaults to None.
        auth_value_lockout (bytes or str): Lockout Hierarchy password. Defaults to None.
        is_provisioned_ok (bool): Do not throw a TSS2_Exception if Fapi is already provisioned. Defaults to True.

    Raises:
        TSS2_Exception: If Fapi returned an error code.

    Returns:
        bool: True if Fapi was provisioned, False otherwise.
    """
    auth_value_eh = _to_bytes_or_null(auth_value_eh)
    auth_value_sh = _to_bytes_or_null(auth_value_sh)
    auth_value_lockout = _to_bytes_or_null(auth_value_lockout, allow_null=False)
    ret = lib.Fapi_Provision(
        self._ctx, auth_value_eh, auth_value_sh, auth_value_lockout
    )
    _chkrc(
        ret,
        acceptable=(
            [lib.TSS2_FAPI_RC_ALREADY_PROVISIONED] if is_provisioned_ok else None
        ),
    )
    return ret == lib.TPM2_RC_SUCCESS
```

--------------------------------

### startup(startup_type)

Source: https://tpm2-pytss.readthedocs.io/en/latest/esys.html

Invokes the TPM2_Startup command in a one-call variant, blocking until the TPM response is available.

```APIDOC
## startup(startup_type)

### Description
Invoke the TPM2_Startup command. This function invokes the TPM2_Startup command in a one-call variant. This means the function will block until the TPM response is available.

### Parameters
- **startup_type** (TPM2_SU) - Required - TPM2_SU_CLEAR or TPM2_SU_STATE.

### Raises
- **TypeError** - If a parameter is not of an expected type.
- **ValueError** - If a parameter is not of an expected value.
- **TSS2_Exception** - Any of the various TSS2_RC’s the lower layers can return.
```

--------------------------------

### get_poll_handles() -> Tuple[PollData]

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/TCTI.html

Gets the poll handles from the TPM.

```APIDOC
## get_poll_handles() -> Tuple[PollData]

### Description
Gets the poll handles from the TPM.

### Returns
- **Tuple[PollData]** - A tuple of PollData objects.
```

--------------------------------

### mac_start

Source: https://tpm2-pytss.readthedocs.io/en/latest/esys.html

Invokes the TPM2_MAC_Start command to begin a MAC sequence.

```APIDOC
## mac_start(handle, auth, hash_alg, session1=255, session2=4095, session3=4095)

### Description
Invokes the TPM2_MAC_Start command in a one-call variant. This function blocks until the TPM response is available.

### Parameters
- **handle** (ESYS_TR) - Required - Handle of an MAC key.
- **auth** (Union[TPM2B_AUTH, bytes, str]) - Required - Authorization value for subsequent use of the sequence.
- **hash_alg** (TPM2_ALG) - Required - The hash algorithm to use for the MAC.
- **session1** (ESYS_TR) - Optional - A session for securing the TPM command. Defaults to ESYS_TR.PASSWORD.
- **session2** (ESYS_TR) - Optional - A session for securing the TPM command. Defaults to ESYS_TR.NONE.
- **session3** (ESYS_TR) - Optional - A session for securing the TPM command. Defaults to ESYS_TR.NONE.

### Returns
- **ESYS_TR** - An ESYS_TR handle of ESYS resource for TPMI_DH_OBJECT.
```

--------------------------------

### Get poll handles

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/TCTI.html

Retrieves file descriptors or handles used for polling the TCTI.

```python
@common_checks()
def get_poll_handles(self) -> Tuple[PollData]:
    """Gets the poll handles from the TPM.

    Returns:
        A tuple of PollData objects.

    Raises:
        TSS2_Exception - Underlying TCTI errors
        Exception - Underlying Python TCTIs can return anything.
    """

    nhandles = ffi.new("size_t *", 0)
    _chkrc(self._v1.getPollHandles(self._ctx, ffi.NULL, nhandles))
    if nhandles[0] == 0:
        return ()
    handles = ffi.new("TSS2_TCTI_POLL_HANDLE []", nhandles[0])
    _chkrc(self._v1.getPollHandles(self._ctx, handles, nhandles))
    rh = []
    for i in range(0, nhandles[0]):
        if os.name == "posix":
            pd = PollData(handles[i].fd, handles[i].events)
        else:
            pd = PollData(handles[i])
        rh.append(pd)
    return tuple(rh)
```

--------------------------------

### FAPI.__init__

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/FAPI.html

Initializes a new FAPI instance, setting up the connection to the TPM2 Feature API context.

```APIDOC
## FAPI(uri: Optional[Union[bytes, str]] = None)

### Description
Initializes the TPM2 Feature API context. This constructor sets up the necessary internal state for FAPI operations.

### Parameters
- **uri** (Optional[Union[bytes, str]]) - Optional - The URI string used to initialize the FAPI context.
```

--------------------------------

### Get Calculated Policy Digest

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/policy.html

Retrieves the digest of the calculated policy as a TPM2B_DIGEST object.

```python
    def get_calculated_digest(self) -> TPM2B_DIGEST:
        """Get the digest of the calculated policy

        Returns:
            The digest as a TPM2B_DIGEST.

        Raises:
            TSS2_Exception
        """
        dig = ffi.new("TPM2B_DIGEST *")
        _chkrc(lib.Tss2_PolicyGetCalculatedDigest(self._ctx, dig))
        return TPM2B_DIGEST(_cdata=dig[0])
```

--------------------------------

### hash_sequence_start(auth, hash_alg, session1=4095, session2=4095, session3=4095)

Source: https://tpm2-pytss.readthedocs.io/en/latest/esys.html

Invokes the TPM2_HashSequenceStart command to begin a hash sequence.

```APIDOC
## hash_sequence_start

### Description
Invokes the TPM2_HashSequenceStart command in a one-call variant. This function blocks until the TPM response is available.

### Parameters
- **auth** (Union[TPM2B_AUTH, bytes, str]) - Required - Authorization value for subsequent use of the sequence.
- **hash_alg** (TPM2_ALG) - Required - The hash algorithm to use for the hash sequence.
- **session1** (ESYS_TR) - Optional - Session for securing the TPM command. Defaults to ESYS_TR.PASSWORD.
- **session2** (ESYS_TR) - Optional - Session for securing the TPM command. Defaults to ESYS_TR.NONE.
- **session3** (ESYS_TR) - Optional - Session for securing the TPM command. Defaults to ESYS_TR.NONE.
```

--------------------------------

### Get Calculated Policy JSON

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/policy.html

Retrieves the calculated policy as a JSON byte string.

```python
    def get_calculated_json(self) -> bytes:
        """Get the calculated policy as JSON

        Returns:
            The calculated JSON policy as bytes

        Raises:
            TSS2_Exception
        """
        size = ffi.new("size_t *")
        _chkrc(lib.Tss2_PolicyGetCalculatedJSON(self._ctx, ffi.NULL, size))

        cjson = ffi.new("uint8_t[]", size[0])
        _chkrc(lib.Tss2_PolicyGetCalculatedJSON(self._ctx, cjson, size))

        return ffi.string(cjson, size[0])
```

--------------------------------

### TCTILdr.__init__(name=None, conf=None)

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/TCTILdr.html

Initializes a new TCTI context loader instance. This constructor sets up the TCTI context using the provided name and configuration string.

```APIDOC
## TCTILdr.__init__(name=None, conf=None)

### Description
Initializes a new TCTI context loader instance. This constructor sets up the TCTI context using the provided name and configuration string.

### Parameters
- **name** (str/bytes) - Optional - The name of the TCTI module to load.
- **conf** (str/bytes) - Optional - The configuration string for the TCTI module.
```

--------------------------------

### Get Signature Algorithm

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/cryptography.html

Retrieves the signature algorithm configuration, defaulting to ECDSA if no scheme is specified.

```python
def get_signature_algorithm(self) -> ec.EllipticCurveSignatureAlgorithm:
    """Get a padding configuration for use with the sign method.

    If the key has a scheme specified, use that scheme.
    Otherwise, use ECDSA as the default

    Returns: an instance of :py:class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurveSignatureAlgorithm`

    Raises:
        ValueError: If the either the scheme or digest algorithm is unsupported.
    """
    if self._public.parameters.eccDetail.scheme.scheme == TPM2_ALG.NULL:
        scheme = TPMT_ECC_SCHEME(scheme=TPM2_ALG.ECDSA)
        scheme.details.anySig.hashAlg = self._public.nameAlg
    else:
        scheme = self._public.parameters.eccDetail.scheme
    if scheme.scheme == TPM2_ALG.ECDSA:
        algorithm = self.get_digest_algorithm()
        sig_alg = ec.ECDSA(algorithm())
    else:
        raise ValueError(f"unsupported signature scheme {scheme.scheme}")
    return sig_alg
```

--------------------------------

### Invoke TPM2_Startup

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Executes the TPM2_Startup command, blocking until the TPM responds.

```python
_check_friendly_int(startup_type, "startup_type", TPM2_SU)

_chkrc(lib.Esys_Startup(self._ctx, startup_type))
```

--------------------------------

### FAPIConfig.__init__

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/FAPI.html

Initializes a temporary FAPI environment context. It allows overriding the default FAPI configuration via a dictionary, environment variables, or keyword arguments, and optionally creates temporary directories for the keystore and logs.

```APIDOC
## FAPIConfig(config=None, temp_dirs=True, **kwargs)

### Description
Creates a temporary FAPI environment. The configuration is determined by checking the provided `config` dictionary, the environment variable `TSS2_FAPICONF`, or default system paths. If `temp_dirs` is True, temporary directories for user, system, and log files are created and injected into the configuration.

### Parameters
- **config** (dict) - Optional - FAPI configuration dictionary to use instead of the installed fapi-config.json.
- **temp_dirs** (bool) - Optional - If True, creates temporary keystore and log directories. Defaults to True.
- **kwargs** (dict) - Optional - Additional configuration entries that override those in `config` or the loaded file.
```

--------------------------------

### Convert ESYS_TR constant to string

Source: https://tpm2-pytss.readthedocs.io/en/latest/constants.html

Example of converting an ESYS_TR constant to its lowercase string representation.

```python
str(ESYS_TR.PCR2) -> ‘pcr2’
```

--------------------------------

### Normalize Constant to Lowercase String

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/constants.html

Use the __str__ method to get a lowercase string representation of a constant.

```python
str(ESYS_TR.PCR2) -> 'pcr2'
```

--------------------------------

### Get Random Bytes via ESAPI

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Internal implementation for retrieving random bytes from the TPM using Esys_GetRandom.

```python
        random_bytes = ffi.new("TPM2B_DIGEST **")
        _chkrc(
            lib.Esys_GetRandom(
                self._ctx, session1, session2, session3, bytes_requested, random_bytes
            )
        )

        return TPM2B_DIGEST(_get_dptr(random_bytes, lib.Esys_Free))
```

--------------------------------

### field_upgrade_start

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Invokes the TPM2_FieldUpgradeStart command to initiate a field upgrade sequence, validating the manifest signature using the provided key handle.

```APIDOC
## field_upgrade_start(key_handle, fu_digest, manifest_signature, authorization=ESYS_TR.PLATFORM, session1=ESYS_TR.PASSWORD, session2=ESYS_TR.NONE, session3=ESYS_TR.NONE)

### Description
Invokes the TPM2_FieldUpgradeStart command in a one-call variant. This function blocks until the TPM response is available.

### Parameters
- **key_handle** (ESYS_TR) - Required - Handle of a public area containing the TPM Vendor Authorization Key.
- **fu_digest** (Union[TPM2B_DIGEST, bytes, str]) - Required - Digest of the first block in the field upgrade sequence.
- **manifest_signature** (TPMT_SIGNATURE) - Required - Signature over fuDigest using the key associated with keyHandle.
- **authorization** (ESYS_TR) - Optional - Defaults to ESYS_TR.PLATFORM.
- **session1** (ESYS_TR) - Optional - Defaults to ESYS_TR.PASSWORD.
- **session2** (ESYS_TR) - Optional - Defaults to ESYS_TR.NONE.
- **session3** (ESYS_TR) - Optional - Defaults to ESYS_TR.NONE.

### Returns
- **None**
```

--------------------------------

### provision(auth_value_eh=None, auth_value_sh=None, auth_value_lockout=None, is_provisioned_ok=True)

Source: https://tpm2-pytss.readthedocs.io/en/latest/fapi.html

Provisions the Feature API, creating the keystore and TPM objects.

```APIDOC
## provision(auth_value_eh=None, auth_value_sh=None, auth_value_lockout=None, is_provisioned_ok=True)

### Description
Provision the Feature API. Creates the keystore and creates some TPM objects.

### Parameters
- **auth_value_eh** (bytes or str) - Optional - Endorsement Hierarchy password.
- **auth_value_sh** (bytes or str) - Optional - Storage/Owner Hierarchy password.
- **auth_value_lockout** (bytes or str) - Optional - Lockout Hierarchy password.
- **is_provisioned_ok** (bool) - Optional - Do not throw a TSS2_Exception if Fapi is already provisioned.

### Returns
- **bool** - True if Fapi was provisioned, False otherwise.

### Raises
- **TSS2_Exception** - If Fapi returned an error code.
```

--------------------------------

### Convert integer to ESYS_TR string name

Source: https://tpm2-pytss.readthedocs.io/en/latest/constants.html

Example of converting a raw integer value to its corresponding ESYS_TR constant name.

```python
ESYS_TR.to_string(5) -> ‘ESYS_TR.PCR5’
```

--------------------------------

### policy.__init__

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/policy.html

Initializes a new policy object using a JSON-formatted policy string or bytes and a specified hash algorithm.

```APIDOC
## policy(policy, hash_alg)

### Description
Initializes the policy object based on the TCG TSS 2.0 JSON Data Types and Policy Language Specification.

### Parameters
- **policy** (Union[bytes, str]) - Required - The JSON policy to calculate or execute.
- **hash_alg** (TPM2_ALG) - Required - The hash algorithm to use for policy calculations.
```

--------------------------------

### Implement TPM2_Create command

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Internal implementation of the Create command, handling parameter validation and FFI memory allocation.

```python
_check_handle_type(parent_handle, "parent_handle")
_check_handle_type(session1, "session1")
_check_handle_type(session2, "session2")
_check_handle_type(session3, "session3")

in_public_cdata = _get_cdata(in_public, TPM2B_PUBLIC, "in_public")

if in_sensitive is None:
    in_sensitive = TPM2B_SENSITIVE_CREATE()
in_sensitive_cdata = _get_cdata(
    in_sensitive, TPM2B_SENSITIVE_CREATE, "in_sensitive"
)
outside_info_cdata = _get_cdata(outside_info, TPM2B_DATA, "outside_info")
creation_pCR_cdata = _get_cdata(
    creation_pcr, TPML_PCR_SELECTION, "creation_pcr"
)

out_private = ffi.new("TPM2B_PRIVATE **")
out_public = ffi.new("TPM2B_PUBLIC **")
creation_data = ffi.new("TPM2B_CREATION_DATA **")
creation_hash = ffi.new("TPM2B_DIGEST **")
creation_ticket = ffi.new("TPMT_TK_CREATION **")
_chkrc(
    lib.Esys_Create(
        self._ctx,
        parent_handle,
        session1,
        session2,
        session3,
        in_sensitive_cdata,
        in_public_cdata,
        outside_info_cdata,
        creation_pCR_cdata,
        out_private,
        out_public,
        creation_data,
        creation_hash,
        creation_ticket,
    )
)
return (
    TPM2B_PRIVATE(_get_dptr(out_private, lib.Esys_Free)),
    TPM2B_PUBLIC(_get_dptr(out_public, lib.Esys_Free)),
    TPM2B_CREATION_DATA(_get_dptr(creation_data, lib.Esys_Free)),
    TPM2B_DIGEST(_get_dptr(creation_hash, lib.Esys_Free)),
    TPMT_TK_CREATION(_get_dptr(creation_ticket, lib.Esys_Free)),
)
```

--------------------------------

### Configure ldconfig for Custom Library Paths

Source: https://tpm2-pytss.readthedocs.io/en/latest/_sources/install.rst.txt

Commands to register /usr/local/lib in the system's dynamic linker configuration.

```console
$ sudo mkdir -p /etc/ld.so.conf.d/
$ echo 'include /etc/ld.so.conf.d/*.conf' | sudo tee -a /etc/ld.so.conf
$ echo '/usr/local/lib' | sudo tee -a /etc/ld.so.conf.d/libc.conf
$ sudo ldconfig
```

--------------------------------

### TPML_Iterator usage example

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/types.html

Shows how the iterator class enables standard Python for-loop iteration over TPML data types.

```python
for alg in TPML_ALG:
   do_something(alg)
```

--------------------------------

### field_upgrade_start

Source: https://tpm2-pytss.readthedocs.io/en/latest/esys.html

Invokes the TPM2_FieldUpgradeStart command to initiate a field upgrade sequence.

```APIDOC
## field_upgrade_start(key_handle, fu_digest, manifest_signature, authorization=268, session1=255, session2=4095, session3=4095)

### Description
Invokes the TPM2_FieldUpgradeStart command in a one-call variant, blocking until the TPM response is available.

### Parameters
- **key_handle** (ESYS_TR) - Required - Handle of a public area containing the TPM Vendor Authorization Key.
- **fu_digest** (Union[TPM2B_DIGEST, bytes, str]) - Required - Digest of the first block in the field upgrade sequence.
- **manifest_signature** (TPMT_SIGNATURE) - Required - Signature over fuDigest.
- **authorization** (ESYS_TR) - Optional - Defaults to ESYS_TR.PLATFORM.
- **session1** (ESYS_TR) - Optional - Defaults to ESYS_TR.PASSWORD.
- **session2** (ESYS_TR) - Optional - Defaults to ESYS_TR.NONE.
- **session3** (ESYS_TR) - Optional - Defaults to ESYS_TR.NONE.

### Exceptions
- TypeError, ValueError, TSS2_Exception
```

--------------------------------

### start_auth_session

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/ESAPI.html

Invokes the TPM2_StartAuthSession command to initiate a new TPM session.

```APIDOC
## start_auth_session(tpm_key, bind, session_type, symmetric, auth_hash, nonce_caller=None, session1=ESYS_TR.NONE, session2=ESYS_TR.NONE, session3=ESYS_TR.NONE)

### Description
Invokes the TPM2_StartAuthSession command in a one-call variant, blocking until the TPM response is received.

### Parameters
- **tpm_key** (ESYS_TR) - Required - Handle of a loaded decrypt key used to encrypt salt.
- **bind** (ESYS_TR) - Required - Entity providing the authValue.
- **session_type** (TPM2_SE) - Required - Indicates the type of the session (HMAC or policy).
- **symmetric** (TPMT_SYM_DEF, str, None) - Required - The algorithm and key size for parameter encryption.
- **auth_hash** (TPM2_ALG, str) - Required - Hash algorithm to use for the session.
- **nonce_caller** (Union[TPM2B_NONCE, bytes, str, None]) - Optional - Initial nonceCaller, defaults to None.
- **session1** (ESYS_TR) - Optional - Session for securing the command, defaults to ESYS_TR.NONE.
- **session2** (ESYS_TR) - Optional - Session for securing the command, defaults to ESYS_TR.NONE.
- **session3** (ESYS_TR) - Optional - Session for securing the command, defaults to ESYS_TR.NONE.

### Returns
- **ESYS_TR** - The handle of the started session.
```

--------------------------------

### Parsing and String Representation of TPMA_LOCALITY

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/constants.html

Examples of parsing locality strings into bitwise values and converting bitwise values back to string representations.

```python
TPMA_LOCALITY.parse("zero|one") -> 0x03
TPMA_LOCALITY.parse("0xf0") -> 0xf0
```

```python
str(TPMA_LOCALITY.THREE|TPMA_LOCALITY.FOUR) -> 'three|four'
str(TPMA_LOCALITY(0xf0)) -> '0xf0'
```

--------------------------------

### FAPI Configuration Management

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/FAPI.html

The FAPIConfig class provides a context manager to create temporary FAPI environments, allowing for configuration overrides and automatic cleanup of temporary directories.

```python
# SPDX-License-Identifier: BSD-2
from .internal.utils import _lib_version_atleast

if not _lib_version_atleast("tss2-fapi", "3.0.0"):
    raise NotImplementedError("FAPI Not installed or version is not 3.0.0")

import contextlib
import json
import logging
import os
import tempfile
from typing import Any, Callable, List, Optional, Tuple, Union

from ._libtpm2_pytss import ffi, lib
from .fapi_info import FapiInfo
from .internal.utils import _chkrc, _check_bug_fixed, _get_dptr, _to_bytes_or_null
from .TCTI import TCTI
from .types import TPM2B_PUBLIC, TPM2B_PRIVATE
from .constants import TSS2_RC, TPM2_ALG
from .TSS2_Exception import TSS2_Exception

logger = logging.getLogger(__name__)

FAPI_CONFIG_ENV = "TSS2_FAPICONF"
FAPI_CONFIG_PATHS = [
    "/etc/tpm2-tss/fapi-config.json",
    "/usr/local/etc/tpm2-tss/fapi-config.json",
]

_cffi_malloc = ffi.new_allocator(free=None)


class FAPIConfig(contextlib.ExitStack):
    """Context to create a temporary Fapi environment."""

    def __init__(self, config: Optional[dict] = None, temp_dirs: bool = True, **kwargs):
        f"""Create a temporary Fapi environment. Get the fapi_conf in this order:
        * `config` if given
        * File specified with environment variable `{FAPI_CONFIG_ENV}` if defined
        * Installed config at `{FAPI_CONFIG_PATHS}`

        Single entries are overridden if additional named arguments are given
        and/or if `temp_dirs` is True.

        Args:
            config (dict): Fapi configuration to use instead of the installed `fapi-config.json`. Defaults to None.
            temp_dirs (bool): Create temporary keystore and log directories and set the respective config entries. Defaults to True.
            **kwargs: Single configuration entries which override those in `config` or `fapi-config.json`.
        """
        super().__init__()

        self.config_env_backup = None
        self.config_tmp_path = None
        self.config = config

        # Return if no custom fapi config is used
        if not (config is not None or temp_dirs or kwargs):
            return

        if self.config is None:
            # Load the currently active fapi-config.json
            config_path = os.environ.get(FAPI_CONFIG_ENV, None)
            if config_path is None:
                for p in FAPI_CONFIG_PATHS:
                    try:
                        with open(p) as file:
                            self.config = json.load(file)
                            break
                    except FileNotFoundError:
                        # keep trying
                        pass

                if self.config is None:
                    raise RuntimeError(
                        f"Could not find fapi config at {FAPI_CONFIG_PATHS}, "
                        f"set env var {FAPI_CONFIG_ENV}"
                    )
            else:
                with open(config_path) as file:
                    self.config = json.load(file)

        self.config = {**self.config, **kwargs}

        if temp_dirs:
            temp_dir_config = {
                "user_dir": self.enter_context(tempfile.TemporaryDirectory()),
                "system_dir": self.enter_context(tempfile.TemporaryDirectory()),
                "log_dir": self.enter_context(tempfile.TemporaryDirectory()),
            }
            conflicting_keys = [k for k in temp_dir_config.keys() if k in kwargs]
            if conflicting_keys:
                raise ValueError(
                    f"Conflicting config entries from temp_dirs and **kwargs: {conflicting_keys}"
                )

            self.config = {**self.config, **temp_dir_config}

        with tempfile.NamedTemporaryFile(mode="w", delete=False) as fapi_conf_file:
            self.config_tmp_path = fapi_conf_file.name
            fapi_conf_file.write(json.dumps(self.config))

        logger.debug(
            f"Creating FAPIConfig: {self.config_tmp_path}:\n{json.dumps(self.config, indent=4)}"
        )

        # Set fapi config env variable
        self.config_env_backup = os.environ.get(FAPI_CONFIG_ENV, None)
        os.environ[FAPI_CONFIG_ENV] = self.config_tmp_path

    def __exit__(self, exc_type, exc_val, exc_tb):
        super().__exit__(exc_type, exc_val, exc_tb)

        if self.config_env_backup is not None:
            os.environ[FAPI_CONFIG_ENV] = self.config_env_backup
        else:
            del os.environ[FAPI_CONFIG_ENV]

        if self.config_tmp_path is not None:
            os.unlink(self.config_tmp_path)
```

--------------------------------

### hmac_start

Source: https://tpm2-pytss.readthedocs.io/en/latest/esys.html

Invokes the TPM2_HMAC_Start command to begin an HMAC sequence.

```APIDOC
## hmac_start(handle, auth, hash_alg, session1=255, session2=4095, session3=4095)

### Description
Invokes the TPM2_HMAC_Start command in a one-call variant. This function blocks until the TPM response is available.

### Parameters
- **handle** (ESYS_TR) - Required - Handle of an HMAC key.
- **auth** (Union[TPM2B_AUTH, bytes, str]) - Required - Authorization value for subsequent use of the sequence.
- **hash_alg** (TPM2_ALG) - Required - The hash algorithm to use for the HMAC.
- **session1** (ESYS_TR) - Optional - A session for securing the TPM command. Defaults to ESYS_TR.PASSWORD.
- **session2** (ESYS_TR) - Optional - A session for securing the TPM command. Defaults to ESYS_TR.NONE.
- **session3** (ESYS_TR) - Optional - A session for securing the TPM command. Defaults to ESYS_TR.NONE.
```

--------------------------------

### create_nv(path, size, type=None, policy_path=None, auth_value=None, exists_ok=False)

Source: https://tpm2-pytss.readthedocs.io/en/latest/fapi.html

Create non-volatile (NV) storage on the TPM.

```APIDOC
## create_nv(path, size, type=None, policy_path=None, auth_value=None, exists_ok=False)

### Description
Create non-volatile (NV) storage on the TPM.

### Parameters
- **path** (bytes or str) - Required - Path to the NV storage area.
- **size** (int) - Required - Size of the storage area in bytes.
- **type** (bytes or str) - Optional - Type of the storage area. Defaults to None.
- **policy_path** (bytes or str) - Optional - The path to the policy associated with the storage area. Defaults to None.
- **auth_value** (bytes or str) - Optional - Password to protect the new storage area. Defaults to None.
- **exists_ok** (bool) - Optional - Do not throw a TSS2_Exception if an object with the given path already exists. Defaults to False.

### Returns
- **bool** - True if the storage area was created, False otherwise.
```

--------------------------------

### Define Platform and Handle Constants

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/constants.html

Classes for platform specifications and handle types.

```python
class TPM2_PS(TPM_FRIENDLY_INT):
    MAIN = 0x00000000
    PC = 0x00000001
    PDA = 0x00000002
    CELL_PHONE = 0x00000003
    SERVER = 0x00000004
    PERIPHERAL = 0x00000005
    TSS = 0x00000006
    STORAGE = 0x00000007
    AUTHENTICATION = 0x00000008
    EMBEDDED = 0x00000009
    HARDCOPY = 0x0000000A
    INFRASTRUCTURE = 0x0000000B
    VIRTUALIZATION = 0x0000000C
    TNC = 0x0000000D
    MULTI_TENANT = 0x0000000E
    TC = 0x0000000F
```

```python
class TPM2_HT(TPM_FRIENDLY_INT):
    PCR = 0x00
    NV_INDEX = 0x01
    HMAC_SESSION = 0x02
    LOADED_SESSION = 0x02
    POLICY_SESSION = 0x03
    SAVED_SESSION = 0x03
    PERMANENT = 0x40
    TRANSIENT = 0x80
    PERSISTENT = 0x81
```

--------------------------------

### Encode Public Key to PEM

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/types.html

Demonstrates how to export a public key to PEM format using the ESAPI interface.

```python
with ESAPI() as e:
    # public parameter is index 1 in the return tuple
    pub = e.create_primary(None)[1]
    pub.to_pem()
```

--------------------------------

### Define TPMA_STARTUP attributes

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/constants.html

Defines startup-related attribute flags.

```python
class TPMA_STARTUP(TPMA_FRIENDLY_INTLIST):
    CLEAR_PHENABLE = 0x00000001
    CLEAR_SHENABLE = 0x00000002
    CLEAR_EHENABLE = 0x00000004
    CLEAR_PHENABLENV = 0x00000008
    CLEAR_RESERVED1_MASK = 0x7FFFFFF0
    CLEAR_ORDERLY = 0x80000000
```

--------------------------------

### marshal()

Source: https://tpm2-pytss.readthedocs.io/en/latest/constants.html

Marshal the instance into bytes.

```APIDOC
## marshal()

### Description
Marshal instance into bytes.

### Returns
- Returns the marshaled type as bytes.
```

--------------------------------

### get_info

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/FAPI.html

Retrieves system and library information from the FAPI.

```APIDOC
## get_info()

### Description
Returns a JSON-encoded string containing library information and TPM capabilities.

### Returns
- **str** - JSON-encoded info string.
```

--------------------------------

### Execute policy

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/policy.html

Run the policy using the provided ESAPI context and session.

```python
def execute(self, esys_ctx: ESAPI, session: ESYS_TR):
    """Executes the policy

    Args:
        esys_ctx (ESAPI): The ESAPI instance to use during policy execution.
        session (ESYS_TR): The policy session to use during execution.

    Raises:
        TSS2_Exception or any possible exception from a callback function.
    """
    try:
        _chkrc(lib.Tss2_PolicyExecute(self._ctx, esys_ctx._ctx, session))
    except Exception as e:
        if self._callback_exception is not None:
            raise self._callback_exception
        raise e
    finally:
        self._callback_exception = None
```

--------------------------------

### Encode Public Key to OpenSSH

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/types.html

Demonstrates how to export a public key to OpenSSH format.

```python
with ESAPI() as e:
    # public parameter is index 1 in the return tuple
    pub = e.create_primary(None)[1]
    pub.to_ssh()
```

--------------------------------

### ESAPI.__init__

Source: https://tpm2-pytss.readthedocs.io/en/latest/esys.html

Initializes an ESAPI object to manage state and metadata during TPM interactions.

```APIDOC
## class tpm2_pytss.ESAPI(tcti=None)

### Description
Initializes an ESAPI object that holds all the state and metadata information during an interaction with the TPM.

### Parameters
- **tcti** (Union[TCTI, str]) - Optional - The TCTI context used to connect to the TPM. Defaults to None.
```

--------------------------------

### Create a FAPI Key

Source: https://tpm2-pytss.readthedocs.io/en/latest/_modules/tpm2_pytss/FAPI.html

Creates a new key in the FAPI keystore. The exists_ok parameter controls whether an existing path error is suppressed.

```python
        path = _to_bytes_or_null(path)
        type_ = _to_bytes_or_null(type_)
        policy_path = _to_bytes_or_null(policy_path)
        auth_value = _to_bytes_or_null(auth_value)
        ret = lib.Fapi_CreateKey(self._ctx, path, type_, policy_path, auth_value)
        _chkrc(
            ret, acceptable=lib.TSS2_FAPI_RC_PATH_ALREADY_EXISTS if exists_ok else None
        )
        return ret == lib.TPM2_RC_SUCCESS
```

--------------------------------

### marshal()

Source: https://tpm2-pytss.readthedocs.io/en/latest/constants.html

Marshal instance into bytes.

```APIDOC
## marshal()

### Description
Marshal instance into bytes.

### Returns
- (bytes) Returns the marshaled type as bytes.
```

--------------------------------

### create_key(path, type=None, policy_path=None, auth_value=None, exists_ok=False)

Source: https://tpm2-pytss.readthedocs.io/en/latest/fapi.html

Create a cryptographic key inside the TPM.

```APIDOC
## create_key(path, type=None, policy_path=None, auth_value=None, exists_ok=False)

### Description
Create a cryptographic key inside the TPM.

### Parameters
- **path** (bytes or str) - Required - Path to the new key object.
- **type** (bytes or str) - Optional - Comma separated list of key types. Defaults to None.
- **policy_path** (bytes or str) - Optional - The path to the policy associated with the key. Defaults to None.
- **auth_value** (bytes or str) - Optional - Password to key. Defaults to None.
- **exists_ok** (bool) - Optional - Do not throw a TSS2_Exception if an object with the given path already exists. Defaults to False.

### Returns
- **bool** - True if the key was created, False otherwise.
```
Tokens:
Raw