diff options
Diffstat (limited to 'include/libimobiledevice')
| -rw-r--r-- | include/libimobiledevice/afc.h | 29 | ||||
| -rw-r--r-- | include/libimobiledevice/libimobiledevice.h | 33 | ||||
| -rw-r--r-- | include/libimobiledevice/mobile_image_mounter.h | 111 | ||||
| -rw-r--r-- | include/libimobiledevice/ostrace.h | 198 |
4 files changed, 364 insertions, 7 deletions
diff --git a/include/libimobiledevice/afc.h b/include/libimobiledevice/afc.h index 4ad3dbd..3dcb5da 100644 --- a/include/libimobiledevice/afc.h +++ b/include/libimobiledevice/afc.h @@ -145,6 +145,20 @@ LIBIMOBILEDEVICE_API afc_error_t afc_client_free(afc_client_t client); LIBIMOBILEDEVICE_API afc_error_t afc_get_device_info(afc_client_t client, char ***device_information); /** + * Get device information for a connected client. The device information + * returned is the device model as well as the free space, the total capacity + * and blocksize on the accessed disk partition. + * + * @param client The client to get device info for. + * @param device_information A pointer to a plist_t that will be populated + * with key-value pairs (dictionary) representing the device’s + * storage and model information. Free with plist_free(). + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_get_device_info_plist(afc_client_t client, plist_t *device_information); + +/** * Gets a directory listing of the directory requested. * * @param client The client to get a directory listing from. @@ -163,7 +177,7 @@ LIBIMOBILEDEVICE_API afc_error_t afc_read_directory(afc_client_t client, const c * @param client The client to use to get the information of the file. * @param path The fully-qualified path to the file. * @param file_information Pointer to a buffer that will be filled with a - * NULL-terminated list of strings with the file information. Set to NULL + * NULL-terminated list of strings with the file attributes. Set to NULL * before calling this function. Free with afc_dictionary_free(). * * @return AFC_E_SUCCESS on success or an AFC_E_* error value. @@ -171,6 +185,19 @@ LIBIMOBILEDEVICE_API afc_error_t afc_read_directory(afc_client_t client, const c LIBIMOBILEDEVICE_API afc_error_t afc_get_file_info(afc_client_t client, const char *path, char ***file_information); /** + * Gets information about a specific file. + * + * @param client The client to use to get the information of the file. + * @param path The fully-qualified path to the file. + * @param file_information A pointer to a plist_t that will be populated + * with key-value pairs (dictionary) representing the file attributes. + * Free with plist_free(). + * + * @return AFC_E_SUCCESS on success or an AFC_E_* error value. + */ +LIBIMOBILEDEVICE_API afc_error_t afc_get_file_info_plist(afc_client_t client, const char *path, plist_t *file_information); + +/** * Opens a file on the device. * * @param client The client to use to open the file. diff --git a/include/libimobiledevice/libimobiledevice.h b/include/libimobiledevice/libimobiledevice.h index a9d270b..bc57778 100644 --- a/include/libimobiledevice/libimobiledevice.h +++ b/include/libimobiledevice/libimobiledevice.h @@ -31,10 +31,13 @@ extern "C" { #endif #include <stdint.h> -#include <sys/types.h> -#include <sys/stat.h> #include <plist/plist.h> +#if defined(_MSC_VER) +#include <basetsd.h> +typedef SSIZE_T ssize_t; +#endif + #ifndef LIBIMOBILEDEVICE_API #ifdef LIBIMOBILEDEVICE_STATIC #define LIBIMOBILEDEVICE_API @@ -401,12 +404,38 @@ LIBIMOBILEDEVICE_API idevice_error_t idevice_get_handle(idevice_t device, uint32 LIBIMOBILEDEVICE_API idevice_error_t idevice_get_udid(idevice_t device, char **udid); /** + * Returns the device ProductVersion in numerical form, where "X.Y.Z" + * will be returned as (X << 16) | (Y << 8) | Z . + * Use IDEVICE_DEVICE_VERSION macro for easy version comparison. + * @see IDEVICE_DEVICE_VERSION + * + * @param client Initialized device client + * + * @return A numerical representation of the X.Y.Z ProductVersion string + * or 0 if the version cannot be retrieved. + */ +LIBIMOBILEDEVICE_API unsigned int idevice_get_device_version(idevice_t device); + +/** + * Gets a readable error string for a given idevice error code. + * + * @param err An idevice error code + * + * @return A readable error string + */ +LIBIMOBILEDEVICE_API const char* idevice_strerror(idevice_error_t err); + +/** * Returns a static string of the libimobiledevice version. * * @return The libimobiledevice version as static ascii string */ LIBIMOBILEDEVICE_API const char* libimobiledevice_version(); +/* macros */ +/** Helper macro to get a numerical representation of a product version tuple */ +#define IDEVICE_DEVICE_VERSION(maj, min, patch) ((((maj) & 0xFF) << 16) | (((min) & 0xFF) << 8) | ((patch) & 0xFF)) + #ifdef __cplusplus } #endif diff --git a/include/libimobiledevice/mobile_image_mounter.h b/include/libimobiledevice/mobile_image_mounter.h index d4fc3f4..76bb61a 100644 --- a/include/libimobiledevice/mobile_image_mounter.h +++ b/include/libimobiledevice/mobile_image_mounter.h @@ -42,6 +42,7 @@ typedef enum { MOBILE_IMAGE_MOUNTER_E_CONN_FAILED = -3, MOBILE_IMAGE_MOUNTER_E_COMMAND_FAILED = -4, MOBILE_IMAGE_MOUNTER_E_DEVICE_LOCKED = -5, + MOBILE_IMAGE_MOUNTER_E_NOT_SUPPORTED = -6, MOBILE_IMAGE_MOUNTER_E_UNKNOWN_ERROR = -256 } mobile_image_mounter_error_t; @@ -127,7 +128,7 @@ LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_lookup_im * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on succes, or a * MOBILE_IMAGE_MOUNTER_E_* error code otherwise. */ -LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_upload_image(mobile_image_mounter_client_t client, const char *image_type, size_t image_size, const char *signature, uint16_t signature_size, mobile_image_mounter_upload_cb_t upload_cb, void* userdata); +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_upload_image(mobile_image_mounter_client_t client, const char *image_type, size_t image_size, const unsigned char *signature, unsigned int signature_size, mobile_image_mounter_upload_cb_t upload_cb, void* userdata); /** * Mounts an image on the device. @@ -138,19 +139,50 @@ LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_upload_im * @param signature Pointer to a buffer holding the images' signature * @param signature_size Length of the signature image_signature points to * @param image_type Type of image to mount + * @param options A dictionary containing additional key/value pairs to add * @param result Pointer to a plist that will receive the result of the * operation. * * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the * operation has failed. Check the resulting plist for further information. - * Note that there is no unmounting function. The mount persists until the - * device is rebooted. * * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are * invalid, or another error code otherwise. */ -LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_mount_image(mobile_image_mounter_client_t client, const char *image_path, const char *signature, uint16_t signature_size, const char *image_type, plist_t *result); +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_mount_image_with_options(mobile_image_mounter_client_t client, const char *image_path, const unsigned char *signature, unsigned int signature_size, const char *image_type, plist_t options, plist_t *result); + +/** + * Mounts an image on the device. + * + * @param client The connected mobile_image_mounter client. + * @param image_path The absolute path of the image to mount. The image must + * be present before calling this function. + * @param signature Pointer to a buffer holding the images' signature + * @param signature_size Length of the signature image_signature points to + * @param image_type Type of image to mount + * @param result Pointer to a plist that will receive the result of the + * operation. + * + * @note This function may return MOBILE_IMAGE_MOUNTER_E_SUCCESS even if the + * operation has failed. Check the resulting plist for further information. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * MOBILE_IMAGE_MOUNTER_E_INVALID_ARG if on ore more parameters are + * invalid, or another error code otherwise. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_mount_image(mobile_image_mounter_client_t client, const char *image_path, const unsigned char *signature, unsigned int signature_size, const char *image_type, plist_t *result); + +/** + * Unmount a mounted image at given path on the device. + * + * @param client The connected mobile_image_mounter client. + * @param mount_path The mount path of the mounted image on the device. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_unmount_image(mobile_image_mounter_client_t client, const char *mount_path); /** * Hangs up the connection to the mobile_image_mounter service. @@ -165,6 +197,77 @@ LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_mount_ima */ LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_hangup(mobile_image_mounter_client_t client); +/** + * Query the developer mode status of the given device. + * + * @param client The connected mobile_image_mounter client. + * @param result A pointer to a plist_t that will be set to the resulting developer mode status dictionary. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_developer_mode_status(mobile_image_mounter_client_t client, plist_t *result); + +/** + * Query a personalization nonce for the given image type, used for personalized disk images (iOS 17+). + * This nonce is supposed to be added to the TSS request for the corresponding image. + * + * @param client The connected mobile_image_mounter client. + * @param image_type The image_type to get the personalization nonce for, usually `DeveloperDiskImage`. + * @param nonce Pointer that will be set to an allocated buffer with the nonce value. + * @param nonce_size Pointer to an unsigned int that will receive the size of the nonce value. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_nonce(mobile_image_mounter_client_t client, const char* image_type, unsigned char** nonce, unsigned int* nonce_size); + +/** + * Query personalization identitifers for the given image_type. + * + * @param client The connected mobile_image_mounter client. + * @param image_type The image_type to get the personalization identifiers for. Can be NULL. + * @param result A pointer to a plist_t that will be set to the resulting identifier dictionary. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_personalization_identifiers(mobile_image_mounter_client_t client, const char* image_type, plist_t *result); + +/** + * + * @param client The connected mobile_image_mounter client. + * @param image_type The image_type to get the personalization identifiers for. Can be NULL. + * @param signature The signature of the corresponding personalized image. + * @param signature_size The size of signature. + * @param manifest Pointer that will be set to an allocated buffer with the manifest data. + * @param manifest_size Pointer to an unsigned int that will be set to the size of the manifest data. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_query_personalization_manifest(mobile_image_mounter_client_t client, const char* image_type, const unsigned char* signature, unsigned int signature_size, unsigned char** manifest, unsigned int* manifest_size); + +/** + * Roll the personalization nonce. + * + * @param client The connected mobile_image_mounter client. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_roll_personalization_nonce(mobile_image_mounter_client_t client); + +/** + * Roll the Cryptex nonce. + * + * @param client The connected mobile_image_mounter client. + * + * @return MOBILE_IMAGE_MOUNTER_E_SUCCESS on success, + * or a MOBILE_IMAGE_MOUNTER_E_* error code on error. + */ +LIBIMOBILEDEVICE_API mobile_image_mounter_error_t mobile_image_mounter_roll_cryptex_nonce(mobile_image_mounter_client_t client); + #ifdef __cplusplus } #endif diff --git a/include/libimobiledevice/ostrace.h b/include/libimobiledevice/ostrace.h new file mode 100644 index 0000000..f083ba7 --- /dev/null +++ b/include/libimobiledevice/ostrace.h @@ -0,0 +1,198 @@ +/** + * @file libimobiledevice/ostrace.h + * @brief System log and tracing capabilities. + * \internal + * + * Copyright (c) 2020-2025 Nikias Bassen, All Rights Reserved. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef OSTRACE_H +#define OSTRACE_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include <libimobiledevice/libimobiledevice.h> +#include <libimobiledevice/lockdown.h> + +/** Service identifier passed to lockdownd_start_service() to start the os trace relay service */ +#define OSTRACE_SERVICE_NAME "com.apple.os_trace_relay" + +/** Error Codes */ +typedef enum { + OSTRACE_E_SUCCESS = 0, + OSTRACE_E_INVALID_ARG = -1, + OSTRACE_E_MUX_ERROR = -2, + OSTRACE_E_SSL_ERROR = -3, + OSTRACE_E_NOT_ENOUGH_DATA = -4, + OSTRACE_E_TIMEOUT = -5, + OSTRACE_E_PLIST_ERROR = -6, + OSTRACE_E_REQUEST_FAILED = -7, + OSTRACE_E_UNKNOWN_ERROR = -256 +} ostrace_error_t; + +typedef struct ostrace_client_private ostrace_client_private; /**< \private */ +typedef ostrace_client_private *ostrace_client_t; /**< The client handle. */ + +#pragma pack(push,1) +struct ostrace_packet_header_t { + uint8_t marker; + uint32_t type; + uint32_t header_size; // 0x81 + uint32_t pid; + uint64_t procid; // == pid + unsigned char procuuid[16]; // procuuid + uint16_t procpath_len; // path to process + uint64_t aid; // activity id, usually 0 + uint64_t paid; // (parent?) activity id, usually 0 + uint64_t time_sec; // tv.tv_sec 64 bit + uint32_t time_usec; // tv.usec 32 bit + uint8_t unk06; + uint8_t level; // Notice=0, Info=0x01, Debug=0x02, Error=0x10, Fault=0x11 + uint8_t unk07; + uint8_t unk08; + uint8_t unk09; + uint8_t unk10; + uint8_t unk11; + uint8_t unk12; + uint64_t timestamp; // ? + uint32_t thread_id; + uint32_t unk13; // 0 + unsigned char imageuuid[16]; // framework/dylib uuid + uint16_t imagepath_len; // framework/dylib + uint32_t message_len; // actual log message + uint32_t offset; // offset for like timestamp or sth + uint16_t subsystem_len; // "subsystem" + uint16_t unk14; + uint16_t category_len; // "category" + uint16_t unk15; + uint32_t unk16; // 0 +}; +#pragma pack(pop) + +/** Receives unparsed ostrace data from the ostrace service */ +typedef void (*ostrace_activity_cb_t)(const void* buf, size_t len, void *user_data); + +/** Receives archive data from the ostrace service */ +typedef int (*ostrace_archive_write_cb_t)(const void* buf, size_t len, void *user_data); + +/* Interface */ + +/** + * Connects to the os_trace_relay service on the specified device. + * + * @param device The device to connect to. + * @param service The service descriptor returned by lockdownd_start_service. + * @param client Pointer that will point to a newly allocated + * ostrace_client_t upon successful return. Must be freed using + * ostrace_client_free() after use. + * + * @return OSTRACE_E_SUCCESS on success, OSTRACE_E_INVALID_ARG when + * client is NULL, or an OSTRACE_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_client_new(idevice_t device, lockdownd_service_descriptor_t service, ostrace_client_t * client); + +/** + * Starts a new os_trace_relay service on the specified device and connects to it. + * + * @param device The device to connect to. + * @param client Pointer that will point to a newly allocated + * ostrace_client_t upon successful return. Must be freed using + * ostrace_client_free() after use. + * @param label The label to use for communication. Usually the program name. + * Pass NULL to disable sending the label in requests to lockdownd. + * + * @return OSTRACE_E_SUCCESS on success, or an OSTRACE_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_client_start_service(idevice_t device, ostrace_client_t * client, const char* label); + +/** + * Disconnects a ostrace client from the device and frees up the + * ostrace client data. + * + * @param client The ostrace client to disconnect and free. + * + * @return OSTRACE_E_SUCCESS on success, OSTRACE_E_INVALID_ARG when + * client is NULL, or an OSTRACE_E_* error code otherwise. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_client_free(ostrace_client_t client); + +/** + * Starts capturing OS trace activity data of the device using a callback. + * + * Use ostrace_stop_activity() to stop receiving the ostrace. + * + * @param client The ostrace client to use + * @param options Options dictionary to pass to StartActivity request. + * Valid options are MessageFilter (PLIST_INT, default 65535), + * Pid (PLIST_INT, default -1), and StreamFlags (PLIST_INT, default 60) + * @param callback Callback to receive data from ostrace. + * @param user_data Custom pointer passed to the callback function. + * @param user_data_free_func Function pointer that will be called when the + * activity is stopped to release user_data. Can be NULL for none. + * + * @return OSTRACE_E_SUCCESS on success, + * OSTRACE_E_INVALID_ARG when one or more parameters are + * invalid or OSTRACE_E_UNKNOWN_ERROR when an unspecified + * error occurs or an ostrace activity has already been started. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_start_activity(ostrace_client_t client, plist_t options, ostrace_activity_cb_t callback, void* user_data); + +/** + * Stops the ostrace activity. + * + * Use ostrace_start_activity() to start receiving OS trace data. + * + * @param client The ostrace client to use + * + * @return OSTRACE_E_SUCCESS on success, + * OSTRACE_E_INVALID_ARG when one or more parameters are + * invalid or OSTRACE_E_UNKNOWN_ERROR when an unspecified + * error occurs or an ostrace activity has already been started. + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_stop_activity(ostrace_client_t client); + +/** + * Returns a dictionary with all currently running processes on the device. + * + * @param client The ostrace client to use + * @param list Pointer that will receive an allocated PLIST_DICT structure with the process data + * + * @return OSTRACE_E_SUCCESS on success, or an OSTRACE_E_* error code otherwise + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_get_pid_list(ostrace_client_t client, plist_t* list); + +/** + * Creates a syslog archive. + * + * @note The device will close the connection once the transfer is complete. The client + * is not usable after that anymore and must be disposed with ostrace_client_free. + * + * @param client The ostrace client to use + * @param options A dictionary with options for the request. + * Valid parameters are StartTime (PLIST_UINT), SizeLimit (PLIST_UINT), and AgeLimit (PLIST_UINT). + * + * @return OSTRACE_E_SUCCESS on success, or an OSTRACE_E_* error code otherwise + */ +LIBIMOBILEDEVICE_API ostrace_error_t ostrace_create_archive(ostrace_client_t client, plist_t options, ostrace_archive_write_cb_t callback, void* user_data); + +#ifdef __cplusplus +} +#endif + +#endif |