libimobiledevice: libimobiledevice/lockdown.h File Reference

libimobiledevice 1.3.0

Data Structures | Typedefs | Enumerations | Functions
lockdown.h File Reference

Manage device preferences, start services, pairing and activation. More...

## Data Structures
struct | lockdownd_pair_record_t
| A pair record holding device, host and root certificates along the host_id. More...
struct | lockdownd_service_descriptor_t

## Typedefs
typedef struct lockdownd_client_private | lockdownd_client_private
typedef lockdownd_client_private * | lockdownd_client_t
| The client handle.

## Enumerations
enum | lockdownd_error_t { LOCKDOWN_E_SUCCESS = 0, LOCKDOWN_E_INVALID_ARG = -1, LOCKDOWN_E_INVALID_CONF = -2, LOCKDOWN_E_PLIST_ERROR = -3, LOCKDOWN_E_PAIRING_FAILED = -4, LOCKDOWN_E_SSL_ERROR = -5, LOCKDOWN_E_DICT_ERROR = -6, LOCKDOWN_E_RECEIVE_TIMEOUT = -7, LOCKDOWN_E_MUX_ERROR = -8, LOCKDOWN_E_NO_RUNNING_SESSION = -9, LOCKDOWN_E_INVALID_RESPONSE = -10, LOCKDOWN_E_MISSING_KEY = -11, LOCKDOWN_E_MISSING_VALUE = -12, LOCKDOWN_E_GET_PROHIBITED = -13, LOCKDOWN_E_SET_PROHIBITED = -14, LOCKDOWN_E_REMOVE_PROHIBITED = -15, LOCKDOWN_E_IMMUTABLE_VALUE = -16, LOCKDOWN_E_PASSWORD_PROTECTED = -17, LOCKDOWN_E_USER_DENIED_PAIRING = -18, LOCKDOWN_E_PAIRING_DIALOG_RESPONSE_PENDING = -19, LOCKDOWN_E_MISSING_HOST_ID = -20, LOCKDOWN_E_INVALID_HOST_ID = -21, LOCKDOWN_E_SESSION_ACTIVE = -22, LOCKDOWN_E_SESSION_INACTIVE = -23, LOCKDOWN_E_MISSING_SESSION_ID = -24, LOCKDOWN_E_INVALID_SESSION_ID = -25, LOCKDOWN_E_MISSING_SERVICE = -26, LOCKDOWN_E_INVALID_SERVICE = -27, LOCKDOWN_E_SERVICE_LIMIT = -28, LOCKDOWN_E_MISSING_PAIR_RECORD = -29, LOCKDOWN_E_SAVE_PAIR_RECORD_FAILED = -30, LOCKDOWN_E_INVALID_PAIR_RECORD = -31, LOCKDOWN_E_INVALID_ACTIVATION_RECORD = -32, LOCKDOWN_E_MISSING_ACTIVATION_RECORD = -33, LOCKDOWN_E_SERVICE_PROHIBITED = -34, LOCKDOWN_E_ESCROW_LOCKED = -35, LOCKDOWN_E_PAIRING_PROHIBITED_OVER_THIS_CONNECTION = -36, LOCKDOWN_E_FMIP_PROTECTED = -37, LOCKDOWN_E_MC_PROTECTED = -38, LOCKDOWN_E_MC_CHALLENGE_REQUIRED = -39, LOCKDOWN_E_UNKNOWN_ERROR = -256 }
| Error Codes.

## Functions
lockdownd_error_t | lockdownd_client_new (idevice_t device, lockdownd_client_t *client, const char *label)
| Creates a new lockdownd client for the device. More...
lockdownd_error_t | lockdownd_client_new_with_handshake (idevice_t device, lockdownd_client_t *client, const char *label)
| Creates a new lockdownd client for the device and starts initial handshake. More...
lockdownd_error_t | lockdownd_client_free (lockdownd_client_t client)
| Closes the lockdownd client session if one is running and frees up the lockdownd_client struct. More...
lockdownd_error_t | lockdownd_query_type (lockdownd_client_t client, char **type)
| Query the type of the service daemon. More...
lockdownd_error_t | lockdownd_get_value (lockdownd_client_t client, const char *domain, const char *key, plist_t *value)
| Retrieves a preferences plist using an optional domain and/or key name. More...
lockdownd_error_t | lockdownd_set_value (lockdownd_client_t client, const char *domain, const char *key, plist_t value)
| Sets a preferences value using a plist and optional by domain and/or key name. More...
lockdownd_error_t | lockdownd_remove_value (lockdownd_client_t client, const char *domain, const char *key)
| Removes a preference node by domain and/or key name. More...
lockdownd_error_t | lockdownd_start_service (lockdownd_client_t client, const char *identifier, lockdownd_service_descriptor_t *service)
| Requests to start a service and retrieve it's port on success. More...
lockdownd_error_t | lockdownd_start_service_with_escrow_bag (lockdownd_client_t client, const char *identifier, lockdownd_service_descriptor_t *service)
| Requests to start a service and retrieve it's port on success. More...
lockdownd_error_t | lockdownd_start_session (lockdownd_client_t client, const char *host_id, char **session_id, int *ssl_enabled)
| Opens a session with lockdownd and switches to SSL mode if device wants it. More...
lockdownd_error_t | lockdownd_stop_session (lockdownd_client_t client, const char *session_id)
| Closes the lockdownd session by sending the StopSession request. More...
lockdownd_error_t | lockdownd_send (lockdownd_client_t client, plist_t plist)
| Sends a plist to lockdownd. More...
lockdownd_error_t | lockdownd_receive (lockdownd_client_t client, plist_t *plist)
| Receives a plist from lockdownd. More...
lockdownd_error_t | lockdownd_pair (lockdownd_client_t client, lockdownd_pair_record_t pair_record)
| Pairs the device using the supplied pair record. More...
lockdownd_error_t | lockdownd_pair_with_options (lockdownd_client_t client, lockdownd_pair_record_t pair_record, plist_t options, plist_t *response)
| Pairs the device using the supplied pair record and passing the given options. More...
lockdownd_error_t | lockdownd_validate_pair (lockdownd_client_t client, lockdownd_pair_record_t pair_record)
| Validates if the device is paired with the given HostID. More...
lockdownd_error_t | lockdownd_unpair (lockdownd_client_t client, lockdownd_pair_record_t pair_record)
| Unpairs the device with the given HostID and removes the pairing records from the device and host if the internal pairing record management is used. More...
lockdownd_error_t | lockdownd_activate (lockdownd_client_t client, plist_t activation_record)
| Activates the device. More...
lockdownd_error_t | lockdownd_deactivate (lockdownd_client_t client)
| Deactivates the device, returning it to the locked “Activate with iTunes” screen. More...
lockdownd_error_t | lockdownd_enter_recovery (lockdownd_client_t client)
| Tells the device to immediately enter recovery mode. More...
lockdownd_error_t | lockdownd_goodbye (lockdownd_client_t client)
| Sends the Goodbye request to lockdownd signaling the end of communication. More...
void | lockdownd_client_set_label (lockdownd_client_t client, const char *label)
| Sets the label to send for requests to lockdownd. More...
lockdownd_error_t | lockdownd_get_device_udid (lockdownd_client_t client, char **udid)
| Returns the unique id of the device from lockdownd. More...
lockdownd_error_t | lockdownd_get_device_name (lockdownd_client_t client, char **device_name)
| Retrieves the name of the device from lockdownd set by the user. More...
lockdownd_error_t | lockdownd_get_sync_data_classes (lockdownd_client_t client, char ***classes, int *count)
| Calculates and returns the data classes the device supports from lockdownd. More...
lockdownd_error_t | lockdownd_data_classes_free (char **classes)
| Frees memory of an allocated array of data classes as returned by lockdownd_get_sync_data_classes() More...
lockdownd_error_t | lockdownd_service_descriptor_free (lockdownd_service_descriptor_t service)
| Frees memory of a service descriptor as returned by lockdownd_start_service() More...
const char * | lockdownd_strerror (lockdownd_error_t err)
| Gets a readable error string for a given lockdown error code. More...

## Detailed Description

Manage device preferences, start services, pairing and activation.

## Function Documentation

## ◆ lockdownd_activate()

lockdownd_error_t lockdownd_activate | ( | lockdownd_client_t | client,
|  | plist_t | activation_record
| ) |  |

Activates the device.

Only works within an open session. The ActivationRecord plist dictionary must be obtained using the activation protocol requesting from Apple's https webservice.

Parameters

  client | The lockdown client
  activation_record | The activation record plist dictionary

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or activation_record is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken, LOCKDOWN_E_ACTIVATION_FAILED if the activation failed, LOCKDOWN_E_INVALID_ACTIVATION_RECORD if the device reports that the activation_record is invalid

## ◆ lockdownd_client_free()

lockdownd_error_t lockdownd_client_free | ( | lockdownd_client_t | client | ) |

Closes the lockdownd client session if one is running and frees up the lockdownd_client struct.

Parameters

  client | The lockdown client

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_client_new()

lockdownd_error_t lockdownd_client_new | ( | idevice_t | device,
|  | lockdownd_client_t * | client,
|  | const char * | label
| ) |  |

Creates a new lockdownd client for the device.

Note
  This function does not pair with the device or start a session. This has to be done manually by the caller after the client is created. The device disconnects automatically if the lockdown connection idles for more than 10 seconds. Make sure to call lockdownd_client_free() as soon as the connection is no longer needed.

Parameters

  device | The device to create a lockdownd client for
  client | The pointer to the location of the new lockdownd_client
  label | The label to use for communication. Usually the program name.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_client_new_with_handshake()

lockdownd_error_t lockdownd_client_new_with_handshake | ( | idevice_t | device,
|  | lockdownd_client_t * | client,
|  | const char * | label
| ) |  |

Creates a new lockdownd client for the device and starts initial handshake.

The handshake consists out of query_type, validate_pair, pair and start_session calls. It uses the internal pairing record management.

Note
  The device disconnects automatically if the lockdown connection idles for more than 10 seconds. Make sure to call lockdownd_client_free() as soon as the connection is no longer needed.

Parameters

  device | The device to create a lockdownd client for
  client | The pointer to the location of the new lockdownd_client
  label | The label to use for communication. Usually the program name. Pass NULL to disable sending the label in requests to lockdownd.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_INVALID_CONF if configuration data is wrong

## ◆ lockdownd_client_set_label()

void lockdownd_client_set_label | ( | lockdownd_client_t | client,
|  | const char * | label
| ) |  |

Sets the label to send for requests to lockdownd.

Parameters

  client | The lockdown client
  label | The label to set or NULL to disable sending a label

## ◆ lockdownd_data_classes_free()

lockdownd_error_t lockdownd_data_classes_free | ( | char ** | classes | ) |

Frees memory of an allocated array of data classes as returned by lockdownd_get_sync_data_classes()

Parameters

  classes | An array of class names to free.

Returns
  LOCKDOWN_E_SUCCESS on success

## ◆ lockdownd_deactivate()

lockdownd_error_t lockdownd_deactivate | ( | lockdownd_client_t | client | ) |

Deactivates the device, returning it to the locked “Activate with iTunes” screen.

Parameters

  client | The lockdown client

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken

## ◆ lockdownd_enter_recovery()

lockdownd_error_t lockdownd_enter_recovery | ( | lockdownd_client_t | client | ) |

Tells the device to immediately enter recovery mode.

Parameters

  client | The lockdown client

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_get_device_name()

lockdownd_error_t lockdownd_get_device_name | ( | lockdownd_client_t | client,
|  | char ** | device_name
| ) |  |

Retrieves the name of the device from lockdownd set by the user.

Parameters

  client | An initialized lockdownd client.
  device_name | Holds the name of the device. The caller is responsible for freeing the memory.

Returns
  LOCKDOWN_E_SUCCESS on success

## ◆ lockdownd_get_device_udid()

lockdownd_error_t lockdownd_get_device_udid | ( | lockdownd_client_t | client,
|  | char ** | udid
| ) |  |

Returns the unique id of the device from lockdownd.

Parameters

  client | An initialized lockdownd client.
  udid | Holds the unique id of the device. The caller is responsible for freeing the memory.

Returns
  LOCKDOWN_E_SUCCESS on success

## ◆ lockdownd_get_sync_data_classes()

lockdownd_error_t lockdownd_get_sync_data_classes | ( | lockdownd_client_t | client,
|  | char *** | classes,
|  | int * | count
| ) |  |

Calculates and returns the data classes the device supports from lockdownd.

Parameters

  client | An initialized lockdownd client.
  classes | A pointer to store an array of class names. The caller is responsible for freeing the memory which can be done using mobilesync_data_classes_free().
  count | The number of items in the classes array.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_NO_RUNNING_SESSION if no session is open, LOCKDOWN_E_PLIST_ERROR if the received plist is broken

## ◆ lockdownd_get_value()

lockdownd_error_t lockdownd_get_value | ( | lockdownd_client_t | client,
|  | const char * | domain,
|  | const char * | key,
|  | plist_t * | value
| ) |  |

Retrieves a preferences plist using an optional domain and/or key name.

Parameters

  client | An initialized lockdownd client.
  domain | The domain to query on or NULL for global domain
  key | The key name to request or NULL to query for all keys
  value | A plist node representing the result value node

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_goodbye()

lockdownd_error_t lockdownd_goodbye | ( | lockdownd_client_t | client | ) |

Sends the Goodbye request to lockdownd signaling the end of communication.

Parameters

  client | The lockdown client

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_PLIST_ERROR if the device did not acknowledge the request

## ◆ lockdownd_pair()

lockdownd_error_t lockdownd_pair | ( | lockdownd_client_t | client,
|  | lockdownd_pair_record_t | pair_record
| ) |  |

Pairs the device using the supplied pair record.

Parameters

  client | The lockdown client
  pair_record | The pair record to use for pairing. If NULL is passed, then the pair records from the current machine are used. New records will be generated automatically when pairing is done for the first time.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, LOCKDOWN_E_PAIRING_FAILED if the pairing failed, LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id

## ◆ lockdownd_pair_with_options()

lockdownd_error_t lockdownd_pair_with_options | ( | lockdownd_client_t | client,
|  | lockdownd_pair_record_t | pair_record,
|  | plist_t | options,
|  | plist_t * | response
| ) |  |

Pairs the device using the supplied pair record and passing the given options.

Parameters

  client | The lockdown client
  pair_record | The pair record to use for pairing. If NULL is passed, then the pair records from the current machine are used. New records will be generated automatically when pairing is done for the first time.
  options | The pairing options to pass. Can be NULL for no options.
  response | If non-NULL a pointer to lockdownd's response dictionary is returned. The caller is responsible to free the response dictionary with plist_free().

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, LOCKDOWN_E_PAIRING_FAILED if the pairing failed, LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id

## ◆ lockdownd_query_type()

lockdownd_error_t lockdownd_query_type | ( | lockdownd_client_t | client,
|  | char ** | type
| ) |  |

Query the type of the service daemon.

Depending on whether the device is queried in normal mode or restore mode, different types will be returned.

Parameters

  client | The lockdownd client
  type | The type returned by the service daemon. Pass NULL to ignore.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_receive()

lockdownd_error_t lockdownd_receive | ( | lockdownd_client_t | client,
|  | plist_t * | plist
| ) |  |

Receives a plist from lockdownd.

Parameters

  client | The lockdownd client
  plist | The plist to store the received data

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or plist is NULL

## ◆ lockdownd_remove_value()

lockdownd_error_t lockdownd_remove_value | ( | lockdownd_client_t | client,
|  | const char * | domain,
|  | const char * | key
| ) |  |

Removes a preference node by domain and/or key name.

Note
  : Use with caution as this could remove vital information on the device

Parameters

  client | An initialized lockdownd client.
  domain | The domain to query on or NULL for global domain
  key | The key name to remove or NULL remove all keys for the current domain

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_send()

lockdownd_error_t lockdownd_send | ( | lockdownd_client_t | client,
|  | plist_t | plist
| ) |  |

Sends a plist to lockdownd.

Note
  This function is low-level and should only be used if you need to send a new type of message.

Parameters

  client | The lockdownd client
  plist | The plist to send

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or plist is NULL

## ◆ lockdownd_service_descriptor_free()

lockdownd_error_t lockdownd_service_descriptor_free | ( | lockdownd_service_descriptor_t | service | ) |

Frees memory of a service descriptor as returned by lockdownd_start_service()

Parameters

  service | A service descriptor instance to free.

Returns
  LOCKDOWN_E_SUCCESS on success

## ◆ lockdownd_set_value()

lockdownd_error_t lockdownd_set_value | ( | lockdownd_client_t | client,
|  | const char * | domain,
|  | const char * | key,
|  | plist_t | value
| ) |  |

Sets a preferences value using a plist and optional by domain and/or key name.

Parameters

  client | an initialized lockdownd client.
  domain | the domain to query on or NULL for global domain
  key | the key name to set the value or NULL to set a value dict plist
  value | a plist node of any node type representing the value to set

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client or value is NULL

## ◆ lockdownd_start_service()

lockdownd_error_t lockdownd_start_service | ( | lockdownd_client_t | client,
|  | const char * | identifier,
|  | lockdownd_service_descriptor_t * | service
| ) |  |

Requests to start a service and retrieve it's port on success.

Parameters

  client | The lockdownd client
  identifier | The identifier of the service to start
  service | The service descriptor on success or NULL on failure

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if a parameter is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not be started by the device

## ◆ lockdownd_start_service_with_escrow_bag()

lockdownd_error_t lockdownd_start_service_with_escrow_bag | ( | lockdownd_client_t | client,
|  | const char * | identifier,
|  | lockdownd_service_descriptor_t * | service
| ) |  |

Requests to start a service and retrieve it's port on success.

Sends the escrow bag from the device's pair record.

Parameters

  client | The lockdownd client
  identifier | The identifier of the service to start
  service | The service descriptor on success or NULL on failure

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG if a parameter is NULL, LOCKDOWN_E_INVALID_SERVICE if the requested service is not known by the device, LOCKDOWN_E_START_SERVICE_FAILED if the service could not because started by the device, LOCKDOWN_E_INVALID_CONF if the host id or escrow bag are missing from the device record.

## ◆ lockdownd_start_session()

lockdownd_error_t lockdownd_start_session | ( | lockdownd_client_t | client,
|  | const char * | host_id,
|  | char ** | session_id,
|  | int * | ssl_enabled
| ) |  |

Opens a session with lockdownd and switches to SSL mode if device wants it.

Parameters

  client | The lockdownd client
  host_id | The HostID of the computer
  session_id | The new session_id of the created session
  ssl_enabled | Whether SSL communication is used in the session

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when a client or host_id is NULL, LOCKDOWN_E_PLIST_ERROR if the response plist had errors, LOCKDOWN_E_INVALID_HOST_ID if the device does not know the supplied HostID, LOCKDOWN_E_SSL_ERROR if enabling SSL communication failed

## ◆ lockdownd_stop_session()

lockdownd_error_t lockdownd_stop_session | ( | lockdownd_client_t | client,
|  | const char * | session_id
| ) |  |

Closes the lockdownd session by sending the StopSession request.

See also
  lockdownd_start_session

Parameters

  client | The lockdown client
  session_id | The id of a running session

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL

## ◆ lockdownd_strerror()

const char* lockdownd_strerror | ( | lockdownd_error_t | err | ) |

Gets a readable error string for a given lockdown error code.

@params err A lockdownd error code

Returns
  A readable error string

## ◆ lockdownd_unpair()

lockdownd_error_t lockdownd_unpair | ( | lockdownd_client_t | client,
|  | lockdownd_pair_record_t | pair_record
| ) |  |

Unpairs the device with the given HostID and removes the pairing records from the device and host if the internal pairing record management is used.

Parameters

  client | The lockdown client
  pair_record | The pair record to use for unpair. If NULL is passed, then the pair records from the current machine are used.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, LOCKDOWN_E_PAIRING_FAILED if the pairing failed, LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id

## ◆ lockdownd_validate_pair()

lockdownd_error_t lockdownd_validate_pair | ( | lockdownd_client_t | client,
|  | lockdownd_pair_record_t | pair_record
| ) |  |

Validates if the device is paired with the given HostID.

If successful the specified host will become trusted host of the device indicated by the lockdownd preference named TrustedHostAttached. Otherwise the host must be paired using lockdownd_pair() first.

Parameters

  client | The lockdown client
  pair_record | The pair record to validate pairing with. If NULL is passed, then the pair record is read from the internal pairing record management.

Returns
  LOCKDOWN_E_SUCCESS on success, LOCKDOWN_E_INVALID_ARG when client is NULL, LOCKDOWN_E_PLIST_ERROR if the pair_record certificates are wrong, LOCKDOWN_E_PAIRING_FAILED if the pairing failed, LOCKDOWN_E_PASSWORD_PROTECTED if the device is password protected, LOCKDOWN_E_INVALID_HOST_ID if the device does not know the caller's host id