### Install libtatsu

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Install the compiled libtatsu library. Use 'sudo make install' if the destination directory requires elevated permissions.

```shell
make install
```

```shell
sudo make install
```

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

### Configure Build with Custom Prefix

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Pass build options like --prefix to autogen.sh or configure to specify a custom installation directory. This example sets the prefix to /usr/local.

```shell
./autogen.sh --prefix=/usr/local
```

```shell
./configure --prefix=/usr/local
```

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

### Install macOS Dependencies (Homebrew)

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Installs build tools for libtatsu using Homebrew on macOS.

```shell
brew install libtool autoconf automake pkg-config
```

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

### Install Linux Dependencies

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Installs necessary build tools and development libraries for libtatsu on Debian/Ubuntu-based systems.

```shell
sudo apt-get install \
	build-essential \
	pkg-config \
	checkinstall \
	git \
	autoconf \
	automake \
	libtool-bin \
	libplist-dev \
	libcurl4-openssl-dev
```

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

### Install macOS Dependencies (MacPorts)

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Installs build tools for libtatsu using MacPorts on macOS.

```shell
sudo port install libtool autoconf automake pkgconfig
```

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

### Query libtatsu version string

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use this function to get the compile-time version string of the installed libtatsu shared library for runtime capability checks.

```c
#include <libtatsu/tatsu.h>
#include <stdio.h>

int main(void) {
    const char *ver = libtatsu_version();
    printf("libtatsu version: %s\n", ver);
    /* Output: libtatsu version: 1.0.5 */
    return 0;
}
```

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

### Install Windows Dependencies (MSYS2)

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Installs required development libraries and tools for libtatsu using MSYS2 on Windows.

```shell
pacman -S base-devel \
	git \
	mingw-w64-x86_64-gcc \
	make \
	libtool \
	autoconf \
	automake-wrapper \
	pkg-config \
        libzstd-devel \
	libcurl-devel
```

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

### Update Library Cache on Linux

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

On Linux systems, run 'sudo ldconfig' after installation to ensure the newly installed libraries are available to the system.

```shell
sudo ldconfig
```

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

### Set PKG_CONFIG_PATH Environment Variable

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Before building, ensure pkg-config can find dependencies by setting the PKG_CONFIG_PATH environment variable. Use a path that matches your dependency installation prefix.

```shell
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
```

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

### libtatsu_version

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Query the library version string. Returns the compile-time version string of the installed libtatsu shared library, useful for runtime capability checks.

```APIDOC
## libtatsu_version

### Description
Query the library version string. Returns the compile-time version string of the installed libtatsu shared library, useful for runtime capability checks.

### Function Signature
```c
const char *libtatsu_version(void);
```

### Example
```c
#include <libtatsu/tatsu.h>
#include <stdio.h>

int main(void) {
    const char *ver = libtatsu_version();
    printf("libtatsu version: %s\n", ver);
    /* Output: libtatsu version: 1.0.5 */
    return 0;
}
```
```

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

### Get Firmware Path by Entry

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Looks up a named entry in the TSS response dictionary and returns its `Path` string value. Returns 0 on success, -1 if the entry or Path key is absent. The caller must free the returned string.

```c
char *path = NULL;
if (tss_response_get_path_by_entry(response, "iBoot", &path) == 0) {
    printf("iBoot path: %s\n", path); /* e.g. "Firmware/all_flash/iBoot.n69.RELEASE.im4p" */
    free(path);
}

```

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

### Get Signing Blob by Firmware Path

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Scans all entries in the TSS response for one whose `Path` matches the given string and returns its `Blob` data. Useful when the component name is unknown but the firmware file path is known. The caller must free the returned blob.

```c
unsigned char *blob = NULL;
int ret = tss_response_get_blob_by_path(response,
              "Firmware/all_flash/iBoot.n69.RELEASE.im4p", &blob);
if (ret == 0) {
    /* use blob for firmware signing */
    free(blob);
}

```

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

### Get Signing Blob by Component Entry Name

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Directly retrieves the `Blob` data from a named dictionary entry in the TSS response. More efficient than path-based lookup when the component name is known. The caller must free the returned blob.

```c
unsigned char *blob = NULL;
if (tss_response_get_blob_by_entry(response, "iBoot", &blob) == 0) {
    /* blob contains the personalized signing ticket for iBoot */
    free(blob);
}

```

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

### Build libtatsu

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Compile the libtatsu library using the make command after successful configuration.

```shell
make
```

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

### Configure libtatsu Build from Tarball

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Run configure to set up the build environment when building from an official release tarball.

```shell
./configure
```

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

### Configure libtatsu Build from Git

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Run autogen.sh to generate the configure script and prepare the source tree for building when cloning from a git repository.

```shell
./autogen.sh
```

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

### Configure libcurl on macOS

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Sets environment variables to use the system's libcurl library on macOS for building libtatsu.

```shell
export libcurl_CFLAGS="-I`xcrun --sdk macosx --show-sdk-path 2>/dev/null`/usr/include"
export libcurl_LIBS="-lcurl"
```

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

### Populate parameters from BuildManifest

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Extracts hardware-identity fields from a BuildIdentity entry in a BuildManifest.plist into a parameters dictionary. Set `include_manifest` to true to also copy the full Manifest component dictionary.

```c
#include <libtatsu/tss.h>
#include <plist/plist.h>
#include <stdio.h>

int main(void) {
    /* Assume build_manifest_data/build_manifest_size holds a BuildManifest.plist */
    plist_t build_manifest = NULL;
    plist_from_xml(build_manifest_data, build_manifest_size, &build_manifest);

    /* Pick the first BuildIdentity (index 0) */
    plist_t identities = plist_dict_get_item(build_manifest, "BuildIdentities");
    plist_t build_identity = plist_array_get_item(identities, 0);

    plist_t parameters = plist_new_dict();

    /* Populate device parameters AND include the full Manifest component dict */
    int ret = tss_parameters_add_from_manifest(parameters, build_identity, true);
    if (ret < 0) {
        fprintf(stderr, "Failed to extract parameters from manifest\n");
        plist_free(parameters);
        plist_free(build_manifest);
        return -1;
    }

    /* parameters now contains ApChipID, ApBoardID, UniqueBuildID, Manifest, etc. */
    plist_free(parameters);
    plist_free(build_manifest);
    return 0;
}
```

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

### Clone libtatsu Repository

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Clone the libtatsu project from its GitHub repository and navigate into the project directory to prepare for building from source.

```shell
git clone https://github.com/libimobiledevice/libtatsu
cd libtatsu
```

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

### Add application processor firmware component tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds applicable firmware component entries from the Manifest dict in parameters. Skips BasebandFirmware, diagnostic-only, and FTAB components. Parameters must include the full Manifest dict.

```c
#include <libtatsu/tss.h>

/* parameters must include the full Manifest dict (include_manifest=true in tss_parameters_add_from_manifest) */
int ret = tss_request_add_ap_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add AP component tags\n");
}
```

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

### tss_parameters_add_from_manifest

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Populate parameters from a BuildManifest identity. Extracts all hardware-identity fields from a BuildIdentity entry into a parameters dict. Optionally copies the full Manifest component dictionary.

```APIDOC
## tss_parameters_add_from_manifest

### Description
Populate parameters from a BuildManifest identity. Extracts all hardware-identity fields (chip IDs, board IDs, security domain, etc.) from one `BuildIdentity` entry in a parsed `BuildManifest.plist` into a flat `parameters` dict. Passing `include_manifest = true` also copies the full `Manifest` component dictionary.

### Function Signature
```c
int tss_parameters_add_from_manifest(plist_t parameters, plist_t build_identity, bool include_manifest);
```

### Parameters
*   **parameters** (plist_t) - The dictionary to populate with parameters.
*   **build_identity** (plist_t) - The `BuildIdentity` plist entry.
*   **include_manifest** (bool) - Whether to include the full `Manifest` component dictionary.

### Return Value
Returns 0 on success, or a negative value on error.

### Example
```c
#include <libtatsu/tss.h>
#include <plist/plist.h>
#include <stdio.h>

int main(void) {
    /* Assume build_manifest_data/build_manifest_size holds a BuildManifest.plist */
    plist_t build_manifest = NULL;
    plist_from_xml(build_manifest_data, build_manifest_size, &build_manifest);

    /* Pick the first BuildIdentity (index 0) */
    plist_t identities = plist_dict_get_item(build_manifest, "BuildIdentities");
    plist_t build_identity = plist_array_get_item(identities, 0);

    plist_t parameters = plist_new_dict();

    /* Populate device parameters AND include the full Manifest component dict */
    int ret = tss_parameters_add_from_manifest(parameters, build_identity, true);
    if (ret < 0) {
        fprintf(stderr, "Failed to extract parameters from manifest\n");
        plist_free(parameters);
        plist_free(build_manifest);
        return -1;
    }

    /* parameters now contains ApChipID, ApBoardID, UniqueBuildID, Manifest, etc. */
    plist_free(parameters);
    plist_free(build_manifest);
    return 0;
}
```
```

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

### Extract and Navigate Release Tarball

Source: https://github.com/libimobiledevice/libtatsu/blob/master/README.md

Extract the libtatsu release tarball and change into the extracted directory to prepare for building from a release archive.

```shell
tar xjf libtatsu-x.y.z.tar.bz2
cd libtatsu-x.y.z
```

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

### Add Yonkers coprocessor firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use this function to add tags for Yonkers coprocessor firmware. It includes ticket information, parameter fields, SEP digest, and specific manifest entries. Ensure the request and parameters are valid.

```c
#include <libtatsu/tss.h>

char *comp_name = NULL;
int ret = tss_request_add_yonkers_tags(request, parameters, NULL, &comp_name);
if (ret < 0) {
    fprintf(stderr, "Failed to add Yonkers tags\n");
} else {
    free(comp_name);
}
```

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

### Add Savage coprocessor firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds @BBTicket, @Savage,Ticket, and Savage-specific fields, including selecting the appropriate Savage component. Optionally writes the chosen component name to *component_name. Parameters must contain Savage,UID, Savage,PatchEpoch, Savage,ChipID, mode flags, and the SEP digest.

```c
#include <libtatsu/tss.h>
#include <stdio.h>

char *comp_name = NULL;
int ret = tss_request_add_savage_tags(request, parameters, NULL, &comp_name);
if (ret < 0) {
    fprintf(stderr, "Failed to add Savage tags\n");
} else {
    printf("Savage component: %s\n", comp_name); /* e.g. "Savage,B0-Prod-Patch" */
    free(comp_name);
}
```

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

### Add Rose (Rap) coprocessor firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use this function to add tags for Rose (Rap) coprocessor firmware. It includes ticket information and various Rap-specific identity, nonce, and manifest fields.

```c
#include <libtatsu/tss.h>

int ret = tss_request_add_rose_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Rose (Rap) tags\n");
}
```

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

### Add Timer coprocessor firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

This function adds tags for Timer coprocessor firmware. It requires parameters including TicketName, TagNumber, and various Timer-specific fields for the given tag number. Ensure all required parameters are provided.

```c
#include <libtatsu/tss.h>

/* parameters must contain TicketName (e.g. "Timer,Ticket,1"), TagNumber (e.g. 1),
   Timer,BoardID,1, Timer,ChipID,1, Timer,SecurityDomain,1, Timer,SecurityMode,1,
   Timer,ProductionMode,1, Timer,ECID,1, Timer,Nonce,1 */
int ret = tss_request_add_timer_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Timer tags\n");
}
```

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

### Add baseband firmware ticket tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds @BBTicket and baseband-specific fields, including the BasebandFirmware component entry. Parameters must contain BbChipID, BbSNUM, BbNonce, BbGoldCertId, and Manifest/BasebandFirmware.

```c
#include <libtatsu/tss.h>

/* parameters must contain BbChipID, BbSNUM, BbNonce, BbGoldCertId, Manifest/BasebandFirmware */
int ret = tss_request_add_baseband_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add baseband tags\n");
}
```

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

### Add eUICC (Vinyl) firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

This function adds tags for eUICC (Vinyl) firmware. It requires specific parameters like eUICC,ChipID, eUICC,EID, and eUICC,RootKeyIdentifier. Ensure these are provided in the parameters argument.

```c
#include <libtatsu/tss.h>

/* parameters must contain eUICC,ChipID, eUICC,EID, eUICC,RootKeyIdentifier, etc. */
int ret = tss_request_add_vinyl_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add eUICC (Vinyl) tags\n");
}
```

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

### Add Secure Enclave firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds @BBTicket and Secure Enclave specific fields, stripping Development or Production CMAC/hash fields based on SE,IsDev. Parameters must contain SE,ChipID, SE,ID, SE,Nonce, SE,RootKeyIdentifier, and SE,IsDev.

```c
#include <libtatsu/tss.h>

/* parameters must contain SE,ChipID, SE,ID, SE,Nonce, SE,RootKeyIdentifier, SE,IsDev */
int ret = tss_request_add_se_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add SE tags\n");
}
```

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

### Add AP img3 ticket tags (legacy devices)

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use for older devices that do not support img4. Parameters must include ApNonce, ApBoardID, ApChipID, ApSecurityDomain, and ApProductionMode.

```c
#include <libtatsu/tss.h>

/* parameters must contain ApNonce, ApBoardID, ApChipID, ApSecurityDomain, ApProductionMode */
int ret = tss_request_add_ap_img3_tags(request, parameters);
if (ret < 0) {
    fprintf(stderr, "Failed to add AP img3 tags\n");
}
```

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

### Add AP img4 ticket tags (modern devices)

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use for all devices supporting the img4 signing format. Parameters must include ApNonce, ApSecurityMode, and ApProductionMode at a minimum.

```c
#include <libtatsu/tss.h>

/* parameters must contain ApNonce, ApSecurityMode, ApProductionMode (at minimum) */
int ret = tss_request_add_ap_img4_tags(request, parameters);
if (ret < 0) {
    fprintf(stderr, "Failed to add AP img4 tags\n");
}
```

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

### Add AP recovery OS component tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Filters for RecoveryOS-specific components, excluding many full-restore-only entries. No specific parameter requirements are listed beyond those for the general AP tags.

```c
#include <libtatsu/tss.h>

int ret = tss_request_add_ap_recovery_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add AP recovery tags\n");
}
```

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

### Create a new TSS request dictionary

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Allocates a new plist dictionary pre-populated with host platform info, version info, and a random UUID. An optional `overrides` plist can be merged to inject or override fields.

```c
#include <libtatsu/tss.h>
#include <plist/plist.h>

/* Create a plain request with no overrides */
plist_t request = tss_request_new(NULL);

/* Create a request with a custom field override */
plist_t overrides = plist_new_dict();
plist_dict_set_item(overrides, "ApProductionMode", plist_new_bool(1));
plist_t request2 = tss_request_new(overrides);
plist_free(overrides);

/* ... populate more tags, then send ... */
plist_free(request);
plist_free(request2);
```

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

### tss_request_new

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Create a new TSS request dictionary. Allocates a new plist dict pre-populated with host platform info, version info, and a random UUID. An optional overrides plist can be merged in.

```APIDOC
## tss_request_new

### Description
Create a new TSS request dictionary. Allocates a new plist dict pre-populated with `@HostPlatformInfo` (`"mac"` or `"windows"`), `@VersionInfo` (the libauthinstall client version string), and a randomly generated `@UUID`. An optional `overrides` plist is merged in last, letting callers inject or override any field.

### Function Signature
```c
plist_t tss_request_new(plist_t overrides);
```

### Parameters
*   **overrides** (plist_t) - An optional plist containing fields to override or add to the request.

### Return Value
A new `plist_t` representing the TSS request dictionary.

### Example
```c
#include <libtatsu/tss.h>
#include <plist/plist.h>

/* Create a plain request with no overrides */
plist_t request = tss_request_new(NULL);

/* Create a request with a custom field override */
plist_t overrides = plist_new_dict();
plist_dict_set_item(overrides, "ApProductionMode", plist_new_bool(1));
plist_t request2 = tss_request_new(overrides);
plist_free(overrides);

/* ... populate more tags, then send ... */
plist_free(request);
plist_free(request2);
```
```

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

### Add TCON (Baobab) display controller tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use this function to add tags for TCON (Baobab) display controller firmware. It includes ticket information, identity fields, and manifest components, with EPRO set from Baobab,ProductionMode.

```c
#include <libtatsu/tss.h>

int ret = tss_request_add_tcon_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add TCON (Baobab) tags\n");
}
```

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

### Add Cryptex personalization tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Use this function to build a Cryptex1 or Cryptex1LocalPolicy TSS request. It handles local policy path if specified, otherwise adds ticket, security mode, production mode, and Cryptex1 fields from parameters. Ensure all required parameters are present for the chosen path.

```c
#include <libtatsu/tss.h>

/* For Cryptex1 request: parameters must contain ApSecurityMode, ApProductionMode,
   ApECID, UniqueBuildID, ApChipID, ApBoardID, ApSecurityDomain, and all Cryptex1,* fields */
int ret = tss_request_add_cryptex_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Cryptex tags\n");
}
```

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

### Add local policy (personalization) tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds the @ApImg4Ticket flag and LocalPolicy-specific parameters. Parameters must contain Ap,LocalBoot, Ap,LocalPolicy, Ap,NextStageIM4MHash, etc.

```c
#include <libtatsu/tss.h>

/* parameters must contain Ap,LocalBoot, Ap,LocalPolicy, Ap,NextStageIM4MHash, etc. */
int ret = tss_request_add_local_policy_tags(request, parameters);
if (ret < 0) {
    fprintf(stderr, "Failed to add local policy tags\n");
}
```

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

### Extract Legacy APTicket Blob

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Retrieves the `APTicket` binary blob from the TSS response for img3/legacy format. The caller must free the returned buffer.

```c
unsigned char *ticket = NULL;
unsigned int length = 0;

if (tss_response_get_ap_ticket(response, &ticket, &length) == 0) {
    printf("APTicket size: %u bytes\n", length);
    free(ticket);
}

```

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

### tss_response_get_blob_by_path

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Scans all entries in the TSS response for one whose `Path` matches the given string and returns its `Blob` data. This is useful when the component name is unknown but the firmware file path is known.

```APIDOC
## tss_response_get_blob_by_path — Get a signing blob by firmware file path

Scans all entries in the TSS response for one whose `Path` matches the given string and returns its `Blob` data. Useful when the component name is unknown but the firmware file path is known.
```

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

### tss_request_add_savage_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds Savage coprocessor firmware tags, including @BBTicket, @Savage,Ticket, Savage,UID, Savage,PatchEpoch, Savage,ChipID, mode flags, the SEP digest, and the appropriate Savage,B?-{Prod,Dev}-Patch component. Optionally writes the chosen component name to *component_name.

```APIDOC
## tss_request_add_savage_tags

### Description
Adds Savage coprocessor firmware tags. This function includes `@BBTicket`, `@Savage,Ticket`, `Savage,UID`, `Savage,PatchEpoch`, `Savage,ChipID`, mode flags, the SEP digest, and the appropriate `Savage,B?-{Prod,Dev}-Patch` component, which is selected by `Savage,Revision`. Optionally, it can write the chosen component name to `*component_name`.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters.
* `NULL`: This parameter is unused in this context.
* `component_name`: A pointer to a char pointer that will store the name of the selected Savage component if provided.

### Return Value
Returns 0 on success, or a negative value on failure. If `component_name` is provided and not NULL, it will point to the allocated string containing the component name upon success.
```

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

### tss_request_add_timer_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds tags for Timer coprocessor firmware, including ticket information, derived ticket key, and fields/components for a specified tag number.

```APIDOC
## tss_request_add_timer_tags — Add Timer coprocessor firmware tags

### Description
Adds `@BBTicket`, a ticket key derived from `TicketName`, and all `Timer,*` fields and manifest components for the tag number given in `TagNumber`.

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure that must contain `TicketName` (e.g., "Timer,Ticket,1"), `TagNumber` (e.g., 1), and various `Timer,*` fields for the specified tag number (e.g., `Timer,BoardID,1`, `Timer,ChipID,1`, `Timer,SecurityDomain,1`, `Timer,SecurityMode,1`, `Timer,ProductionMode,1`, `Timer,ECID,1`, `Timer,Nonce,1`).

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

/* parameters must contain TicketName (e.g. "Timer,Ticket,1"), TagNumber (e.g. 1),
   Timer,BoardID,1, Timer,ChipID,1, Timer,SecurityDomain,1, Timer,SecurityMode,1,
   Timer,ProductionMode,1, Timer,ECID,1, Timer,Nonce,1 */
int ret = tss_request_add_timer_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Timer tags\n");
}
```
```

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

### tss_request_add_cryptex_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Builds a Cryptex1 or Cryptex1LocalPolicy TSS request, handling local policy or adding standard Cryptex1 tags.

```APIDOC
## tss_request_add_cryptex_tags — Add Cryptex personalization tags

### Description
Builds a Cryptex1 or Cryptex1LocalPolicy TSS request. If `parameters` contains `Ap,LocalPolicy`, it calls the local-policy path; otherwise it adds `@Cryptex1,Ticket`, security mode/production mode booleans, and all `Cryptex1*` fields from parameters.

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure. For a Cryptex1 request, it must contain `ApSecurityMode`, `ApProductionMode`, `ApECID`, `UniqueBuildID`, `ApChipID`, `ApBoardID`, `ApSecurityDomain`, and all `Cryptex1,*` fields. If `Ap,LocalPolicy` is present, it triggers the local-policy path.

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

/* For Cryptex1 request: parameters must contain ApSecurityMode, ApProductionMode,
   ApECID, UniqueBuildID, ApChipID, ApBoardID, ApSecurityDomain, and all Cryptex1,* fields */
int ret = tss_request_add_cryptex_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Cryptex tags\n");
}
```
```

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

### tss_request_add_rose_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds tags for Rose (Rap) coprocessor firmware, including ticket information, identity and nonce fields, and manifest components.

```APIDOC
## tss_request_add_rose_tags — Add Rose (Rap) coprocessor firmware tags

### Description
Adds `@BBTicket`, `@Rap,Ticket`, all `Rap,*` identity and nonce fields, and every `Rap,*` manifest component (with RestoreRequestRules applied).

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure containing `Rap,*` fields.

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

int ret = tss_request_add_rose_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Rose (Rap) tags\n");
}
```
```

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

### tss_request_add_ap_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds application processor firmware component tags by iterating through the Manifest dict in parameters. It respects RestoreRequestRules, Trusted flags, img4 EPRO/ESEC fields, and _OnlyFWComponents filtering, while skipping BasebandFirmware, diagnostic-only, and FTAB components.

```APIDOC
## tss_request_add_ap_tags

### Description
Adds application processor firmware component tags. This function iterates through the `Manifest` dictionary within the `parameters` and adds every applicable firmware component entry to the request. It respects `RestoreRequestRules`, `Trusted` flags, img4 `EPRO`/`ESEC` fields, and `_OnlyFWComponents` filtering. It skips BasebandFirmware, diagnostic-only components, and FTAB components.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters. Must include the full `Manifest` dict (e.g., by setting `include_manifest=true` in `tss_parameters_add_from_manifest`).
* `NULL`: This parameter is unused in this context.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### Add Veridian (BMU) firmware tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

This function adds tags for Veridian (BMU) firmware. It includes ticket information and various BMU-specific board, chip, nonce, mode fields, and manifest components.

```c
#include <libtatsu/tss.h>

int ret = tss_request_add_veridian_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Veridian (BMU) tags\n");
}
```

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

### tss_request_add_yonkers_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds specific tags for Yonkers coprocessor firmware, including ticket information, parameter fields, SEP digest, and manifest entries based on production mode and revision.

```APIDOC
## tss_request_add_yonkers_tags — Add Yonkers coprocessor firmware tags

### Description
Adds `@BBTicket`, `@Yonkers,Ticket`, all `Yonkers,*` parameter fields, the SEP digest, and the single matching `Yonkers,SysTopPatch*` manifest entry selected by `Yonkers,ProductionMode` and `Yonkers,FabRevision`.

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure containing relevant parameters like `Yonkers,ProductionMode`, `Yonkers,FabRevision`, etc.
- **comp_name**: Output parameter for component name (can be NULL).

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

char *comp_name = NULL;
int ret = tss_request_add_yonkers_tags(request, parameters, NULL, &comp_name);
if (ret < 0) {
    fprintf(stderr, "Failed to add Yonkers tags\n");
} else {
    free(comp_name);
}
```
```

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

### tss_request_add_tcon_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds tags for TCON (Baobab) display controller firmware, including ticket information, identity fields, and manifest components.

```APIDOC
## tss_request_add_tcon_tags — Add TCON (Baobab) display controller tags

### Description
Adds `@BBTicket`, `@Baobab,Ticket`, all `Baobab,*` identity fields, and every `Baobab,*` manifest component with `EPRO` set from `Baobab,ProductionMode`.

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure containing `Baobab,*` fields, including `Baobab,ProductionMode`.

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

int ret = tss_request_add_tcon_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add TCON (Baobab) tags\n");
}
```
```

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

### tss_request_add_se_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds Secure Enclave firmware tags, including @BBTicket, SE,ChipID, SE,ID, SE,Nonce, SE,RootKeyIdentifier, and all SE,* manifest entries. It strips Development or Production CMAC/hash fields based on the SE,IsDev parameter.

```APIDOC
## tss_request_add_se_tags

### Description
Adds Secure Enclave firmware tags. This function includes `@BBTicket`, `SE,ChipID`, `SE,ID`, `SE,Nonce`, `SE,RootKeyIdentifier`, and all `SE,*` manifest entries. It strips Development or Production CMAC/hash fields based on the `SE,IsDev` parameter.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters. Must include `SE,ChipID`, `SE,ID`, `SE,Nonce`, `SE,RootKeyIdentifier`, and `SE,IsDev`.
* `NULL`: This parameter is unused in this context.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### tss_request_add_local_policy_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds local policy (personalization) tags, including the @ApImg4Ticket flag and LocalPolicy-specific parameters like Ap,LocalBoot, Ap,LocalPolicy, Ap,NextStageIM4MHash, ApECID, ApChipID, ApBoardID, ApSecurityDomain, ApNonce, ApSecurityMode, and ApProductionMode.

```APIDOC
## tss_request_add_local_policy_tags

### Description
Adds local policy (personalization) tags. This function includes the `@ApImg4Ticket` flag and LocalPolicy-specific parameters such as `Ap,LocalBoot`, `Ap,LocalPolicy`, `Ap,NextStageIM4MHash`, `ApECID`, `ApChipID`, `ApBoardID`, `ApSecurityDomain`, `ApNonce`, `ApSecurityMode`, and `ApProductionMode`.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters. Must include parameters like `Ap,LocalBoot`, `Ap,LocalPolicy`, `Ap,NextStageIM4MHash`, etc.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### Control libtatsu diagnostic verbosity

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Sets the internal debug level for libtatsu. Level 0 silences output, level 1 enables error messages, and level 2 enables verbose debug messages and dumps request/response plists as XML.

```c
#include <libtatsu/tss.h>

/* Enable full debug output before any TSS operations */
tss_set_debug_level(2);
```

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

### Extract BBTicket Blob

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Retrieves the `BBTicket` binary blob from the TSS response, used for baseband firmware personalization. The caller must free the returned buffer.

```c
unsigned char *bb_ticket = NULL;
unsigned int bb_length = 0;

if (tss_response_get_baseband_ticket(response, &bb_ticket, &bb_length) == 0) {
    printf("BBTicket size: %u bytes\n", bb_length);
    free(bb_ticket);
}

```

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

### tss_request_add_baseband_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds baseband firmware ticket tags, including @BBTicket, Bb* chip and key-hash fields, BbNonce, BbGoldCertId, BbSNUM, and the BasebandFirmware component entry. It applies BbChipID-based filtering to remove correct PSI/PSI2 partial-digest entries.

```APIDOC
## tss_request_add_baseband_tags

### Description
Adds baseband firmware ticket tags. This function includes the `@BBTicket`, all `Bb*` chip and key-hash fields, `BbNonce`, `BbGoldCertId`, `BbSNUM`, and the `BasebandFirmware` component entry. It applies `BbChipID`-based filtering to remove the correct PSI/PSI2 partial-digest entries.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters. Must include `BbChipID`, `BbSNUM`, `BbNonce`, `BbGoldCertId`, and `Manifest/BasebandFirmware`.
* `NULL`: This parameter is unused in this context.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### tss_response_get_ap_ticket

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Retrieves the legacy `APTicket` binary blob (img3 format) from the TSS response. The caller must free the returned buffer.

```APIDOC
## tss_response_get_ap_ticket — Extract the legacy APTicket blob

Retrieves the `APTicket` binary blob from the TSS response (img3 / legacy format). The caller must `free()` the returned buffer.
```

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

### tss_request_add_veridian_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds tags for Veridian (BMU) firmware, including ticket information, board/chip/nonce/mode fields, and manifest components.

```APIDOC
## tss_request_add_veridian_tags — Add Veridian (BMU) firmware tags

### Description
Adds `@BBTicket`, `@BMU,Ticket`, all `BMU,*` board/chip/nonce/mode fields, and every `BMU,*` manifest component with RestoreRequestRules applied.

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure containing `BMU,*` fields.

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

int ret = tss_request_add_veridian_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add Veridian (BMU) tags\n");
}
```
```

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

### tss_request_add_ap_recovery_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds AP recovery OS component tags, similar to tss_request_add_ap_tags but specifically filtering for RecoveryOS components and excluding many full-restore-only entries like iBEC, iBSS, RestoreRamDisk, RestoreSEP, and LLB.

```APIDOC
## tss_request_add_ap_recovery_tags

### Description
Adds AP recovery OS component tags. This function is similar to `tss_request_add_ap_tags` but filters specifically for RecoveryOS-specific components. It excludes many entries that are only relevant for full restores, such as iBEC, iBSS, RestoreRamDisk, RestoreSEP, and LLB.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters.
* `NULL`: This parameter is unused in this context.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### tss_response_get_blob_by_entry

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Directly retrieves the `Blob` data from a named dictionary entry in the TSS response. This method is more efficient than path-based lookup when the component name is known.

```APIDOC
## tss_response_get_blob_by_entry — Get a signing blob by component entry name

Directly retrieves the `Blob` data from a named dict entry in the TSS response. More efficient than path-based lookup when the component name is known.
```

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

### tss_response_get_baseband_ticket

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Retrieves the `BBTicket` binary blob from the TSS response, used for baseband firmware personalization. The caller must free the returned buffer.

```APIDOC
## tss_response_get_baseband_ticket — Extract the BBTicket blob

Retrieves the `BBTicket` binary blob from the TSS response for baseband firmware personalization.
```

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

### Extract ApImg4Ticket Blob

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Retrieves the raw `ApImg4Ticket` binary data from the TSS response dictionary. The caller is responsible for freeing the returned buffer.

```c
unsigned char *ticket = NULL;
unsigned int length = 0;

int ret = tss_response_get_ap_img4_ticket(response, &ticket, &length);
if (ret == 0) {
    /* write ticket bytes to shsh2 file */
    FILE *f = fopen("ticket.shsh2", "wb");
    fwrite(ticket, 1, length, f);
    fclose(f);
    free(ticket);
} else {
    fprintf(stderr, "No ApImg4Ticket in TSS response\n");
}

```

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

### tss_request_add_vinyl_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds tags for eUICC (Vinyl) firmware, including ticket information, chip/EID/key-identifier fields, component digests, and nonces.

```APIDOC
## tss_request_add_vinyl_tags — Add eUICC (Vinyl) firmware tags

### Description
Adds `@BBTicket`, `@eUICC,Ticket`, eUICC chip/EID/key-identifier fields, the `eUICC,Gold` and `eUICC,Main` component digests, and per-component nonces from `EUICCGoldNonce` / `EUICCMainNonce`.

### Method
C Function Call

### Parameters
- **request**: Pointer to the TSS request structure.
- **parameters**: A dictionary or structure containing required fields such as `eUICC,ChipID`, `eUICC,EID`, `eUICC,RootKeyIdentifier`, etc.

### Return Value
Returns 0 on success, a negative value on failure.

### Example
```c
#include <libtatsu/tss.h>

/* parameters must contain eUICC,ChipID, eUICC,EID, eUICC,RootKeyIdentifier, etc. */
int ret = tss_request_add_vinyl_tags(request, parameters, NULL);
if (ret < 0) {
    fprintf(stderr, "Failed to add eUICC (Vinyl) tags\n");
}
```
```

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

### tss_request_add_ap_img4_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds AP img4 ticket tags for modern devices, including OS version strings, ApNonce, ApSecurityMode, ApProductionMode, SepNonce/ApSepNonce, NeRDEpoch, UID_MODE, and Ap,SikaFuse. Required for devices supporting the img4 signing format.

```APIDOC
## tss_request_add_ap_img4_tags

### Description
Adds AP img4 ticket tags for modern devices. This includes the `@ApImg4Ticket` flag and img4-specific fields such as OS version strings, `ApNonce`, `ApSecurityMode`, `ApProductionMode`, `SepNonce`/`ApSepNonce`, `NeRDEpoch`, `UID_MODE`, and `Ap,SikaFuse`. This function is required for all devices that support the img4 signing format.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters. Must include `ApNonce`, `ApSecurityMode`, and `ApProductionMode` at a minimum.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### tss_response_get_path_by_entry

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Looks up a named entry in the TSS response dictionary and returns its `Path` string value. Returns 0 on success, -1 if the entry or `Path` key is absent.

```APIDOC
## tss_response_get_path_by_entry — Get the firmware path for a response entry

Looks up a named entry in the TSS response dict and returns its `Path` string value. Returns `0` on success, `-1` if the entry or Path key is absent.
```

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

### tss_request_send

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Serializes a TSS request to XML and sends it to Apple's TSS endpoint. It handles URL rotation, retries, and returns a parsed XML response plist on success or NULL on failure. An optional `server_url_string` can override the built-in URLs.

```APIDOC
## tss_request_send — Serialize and send the TSS request to Apple's server

Serializes the request plist to XML, then POSTs it to Apple's TSS endpoint (rotating through six fallback URLs across `gs.apple.com` and its CDN aliases), retrying up to 15 times. If `server_url_string` is non-NULL it overrides the built-in URL list. Returns the parsed XML response plist on success, or `NULL` on failure.
```

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

### tss_request_add_ap_img3_tags

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Adds AP img3 ticket tags for legacy devices, including ApNonce, ApBoardID, ApChipID, ApSecurityDomain, and ApProductionMode. Used for older devices that do not support img4.

```APIDOC
## tss_request_add_ap_img3_tags

### Description
Adds AP img3 ticket tags for legacy devices. This includes the `@APTicket` flag and legacy img3 fields: `ApNonce`, `ApBoardID`, `ApChipID`, `ApSecurityDomain`, and `ApProductionMode`. This function is used for older devices that do not support img4.

### Parameters
* `request`: A pointer to the TSS request structure.
* `parameters`: A dictionary containing necessary parameters. Must include `ApNonce`, `ApBoardID`, `ApChipID`, `ApSecurityDomain`, and `ApProductionMode`.

### Return Value
Returns 0 on success, or a negative value on failure.
```

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

### Serialize and Send TSS Request

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Serializes a TSS request plist to XML and sends it to Apple's TSS endpoint. Handles retries and fallback URLs. Overrides built-in URLs if `server_url_string` is provided. Returns the parsed XML response plist or NULL on failure.

```c
#include <libtatsu/tss.h>
#include <plist/plist.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    tss_set_debug_level(1); /* show errors */

    plist_t parameters = plist_new_dict();
    /* ... populate parameters from BuildManifest and device info ... */

    plist_t request = tss_request_new(NULL);
    tss_request_add_common_tags(request, parameters, NULL);
    tss_request_add_ap_img4_tags(request, parameters);
    tss_request_add_ap_tags(request, parameters, NULL);

    /* Send to Apple's TSS (NULL = use built-in URL rotation) */
    plist_t response = tss_request_send(request, NULL);
    if (!response) {
        fprintf(stderr, "TSS request failed\n");
        plist_free(request);
        plist_free(parameters);
        return -1;
    }

    /* Extract the ApImg4Ticket from the response */
    unsigned char *ticket = NULL;
    unsigned int ticket_len = 0;
    if (tss_response_get_ap_img4_ticket(response, &ticket, &ticket_len) == 0) {
        printf("Got ApImg4Ticket: %u bytes\n", ticket_len);
        /* Write ticket to file, pass to idevicerestore, etc. */
        free(ticket);
    }

    plist_free(response);
    plist_free(request);
    plist_free(parameters);
    return 0;
}

```

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

### tss_response_get_ap_img4_ticket

Source: https://context7.com/libimobiledevice/libtatsu/llms.txt

Extracts the raw `ApImg4Ticket` binary data from the TSS response dictionary. The caller is responsible for freeing the returned buffer.

```APIDOC
## tss_response_get_ap_img4_ticket — Extract the ApImg4Ticket blob

Retrieves the raw `ApImg4Ticket` binary data from the TSS response dict. The caller owns the returned buffer and must `free()` it.
```