Commit c8cf91ee authored by Matt Colyer's avatar Matt Colyer

Added doxygen to lockdown.c

parent 24718e49
...@@ -46,6 +46,10 @@ int get_rand(int min, int max) { ...@@ -46,6 +46,10 @@ int get_rand(int min, int max) {
return retval; return retval;
} }
/** Generates a valid HostID (which is actually a UUID).
*
* @param A null terminated string containing a valid HostID.
*/
char *lockdownd_generate_hostid() { char *lockdownd_generate_hostid() {
char *hostid = (char*)malloc(sizeof(char) * 37); // HostID's are just UUID's, and UUID's are 36 characters long char *hostid = (char*)malloc(sizeof(char) * 37); // HostID's are just UUID's, and UUID's are 36 characters long
const char *chars = "ABCDEF0123456789"; const char *chars = "ABCDEF0123456789";
...@@ -64,6 +68,12 @@ char *lockdownd_generate_hostid() { ...@@ -64,6 +68,12 @@ char *lockdownd_generate_hostid() {
return hostid; return hostid;
} }
/** Creates a lockdownd client for the give iPhone.
*
* @param phone The iPhone to create a lockdownd client for
*
* @return The lockdownd client.
*/
lockdownd_client *new_lockdownd_client(iPhone *phone) { lockdownd_client *new_lockdownd_client(iPhone *phone) {
if (!phone) return NULL; if (!phone) return NULL;
lockdownd_client *control = (lockdownd_client*)malloc(sizeof(lockdownd_client)); lockdownd_client *control = (lockdownd_client*)malloc(sizeof(lockdownd_client));
...@@ -79,6 +89,10 @@ lockdownd_client *new_lockdownd_client(iPhone *phone) { ...@@ -79,6 +89,10 @@ lockdownd_client *new_lockdownd_client(iPhone *phone) {
return control; return control;
} }
/** Closes the lockdownd client and does the necessary housekeeping.
*
* @param control The lockdown client
*/
void lockdown_close(lockdownd_client *control) { void lockdown_close(lockdownd_client *control) {
if (!control) return; if (!control) return;
if (control->connection) { if (control->connection) {
...@@ -89,7 +103,14 @@ void lockdown_close(lockdownd_client *control) { ...@@ -89,7 +103,14 @@ void lockdown_close(lockdownd_client *control) {
free(control); free(control);
} }
/** Polls the iPhone for lockdownd data.
*
* @param control The lockdownd client
* @param dump_data The pointer to the location of the buffer in which to store
* the received data
*
* @return The number of bytes received
*/
int lockdownd_recv(lockdownd_client *control, char **dump_data) { int lockdownd_recv(lockdownd_client *control, char **dump_data) {
if (!control) return 0; if (!control) return 0;
char *receive; char *receive;
...@@ -106,6 +127,17 @@ int lockdownd_recv(lockdownd_client *control, char **dump_data) { ...@@ -106,6 +127,17 @@ int lockdownd_recv(lockdownd_client *control, char **dump_data) {
return bytes; return bytes;
} }
/** Sends lockdownd data to the iPhone
*
* @note This function is low-level and should only be used if you need to send
* a new type of message.
*
* @param control The lockdownd client
* @param raw_data The null terminated string buffer to send
* @param length The length of data to send
*
* @return The number of bytes sent
*/
int lockdownd_send(lockdownd_client *control, char *raw_data, uint32 length) { int lockdownd_send(lockdownd_client *control, char *raw_data, uint32 length) {
if (!control) return 0; if (!control) return 0;
char *real_query; char *real_query;
...@@ -130,6 +162,14 @@ int lockdownd_send(lockdownd_client *control, char *raw_data, uint32 length) { ...@@ -130,6 +162,14 @@ int lockdownd_send(lockdownd_client *control, char *raw_data, uint32 length) {
return bytes; return bytes;
} }
/** Initiates the handshake for the lockdown session. Part of the lockdownd handshake.
*
* @note You most likely want lockdownd_init unless you are doing something special.
*
* @param control The lockdownd client
*
* @return 1 on success and 0 on failure.
*/
int lockdownd_hello(lockdownd_client *control) { int lockdownd_hello(lockdownd_client *control) {
if (!control) return 0; if (!control) return 0;
xmlDocPtr plist = new_plist(); xmlDocPtr plist = new_plist();
...@@ -172,7 +212,12 @@ int lockdownd_hello(lockdownd_client *control) { ...@@ -172,7 +212,12 @@ int lockdownd_hello(lockdownd_client *control) {
free_dictionary(dictionary); free_dictionary(dictionary);
return 0; return 0;
} }
/** Askes for the device's public key. Part of the lockdownd handshake.
*
* @note You most likely want lockdownd_init unless you are doing something special.
*
* @return 1 on success and 0 on failure.
*/
int lockdownd_get_device_public_key(lockdownd_client *control, char **public_key) int lockdownd_get_device_public_key(lockdownd_client *control, char **public_key)
{ {
xmlDocPtr plist = new_plist(); xmlDocPtr plist = new_plist();
...@@ -228,7 +273,11 @@ int lockdownd_get_device_public_key(lockdownd_client *control, char **public_key ...@@ -228,7 +273,11 @@ int lockdownd_get_device_public_key(lockdownd_client *control, char **public_key
return success; return success;
} }
/** /** Completes the entire lockdownd handshake.
*
* @param phone The iPhone
* @param lockdownd_client The pointer to the location of the lockdownd_client
*
* @return 1 on success and 0 on failure * @return 1 on success and 0 on failure
*/ */
int lockdownd_init(iPhone *phone, lockdownd_client **control) int lockdownd_init(iPhone *phone, lockdownd_client **control)
...@@ -272,7 +321,11 @@ int lockdownd_init(iPhone *phone, lockdownd_client **control) ...@@ -272,7 +321,11 @@ int lockdownd_init(iPhone *phone, lockdownd_client **control)
return ret; return ret;
} }
/** /** Generates the appropriate keys and pairs the device. It's part of the
* lockdownd handshake.
*
* @note You most likely want lockdownd_init unless you are doing something special.
*
* @return 1 on success and 0 on failure * @return 1 on success and 0 on failure
*/ */
int lockdownd_pair_device(lockdownd_client *control, char *public_key_b64, char *host_id) int lockdownd_pair_device(lockdownd_client *control, char *public_key_b64, char *host_id)
...@@ -359,7 +412,9 @@ int lockdownd_pair_device(lockdownd_client *control, char *public_key_b64, char ...@@ -359,7 +412,9 @@ int lockdownd_pair_device(lockdownd_client *control, char *public_key_b64, char
return ret; return ret;
} }
/** /** Generates the device certificate from the public key as well as the host
* and root certificates.
*
* @return 1 on success and 0 on failure. * @return 1 on success and 0 on failure.
*/ */
int lockdownd_gen_pair_cert(char *public_key_b64, char **device_cert_b64, char **host_cert_b64, char **root_cert_b64) int lockdownd_gen_pair_cert(char *public_key_b64, char **device_cert_b64, char **host_cert_b64, char **root_cert_b64)
...@@ -488,6 +543,13 @@ int lockdownd_gen_pair_cert(char *public_key_b64, char **device_cert_b64, char * ...@@ -488,6 +543,13 @@ int lockdownd_gen_pair_cert(char *public_key_b64, char **device_cert_b64, char *
} }
} }
/** Starts SSL communication with lockdownd after the iPhone has been paired.
*
* @param control The lockdownd client
* @param HostID The HostID used with this phone
*
* @return 1 on success and 0 on failure
*/
int lockdownd_start_SSL_session(lockdownd_client *control, const char *HostID) { int lockdownd_start_SSL_session(lockdownd_client *control, const char *HostID) {
xmlDocPtr plist = new_plist(); xmlDocPtr plist = new_plist();
xmlNode *dict = add_child_to_plist(plist, "dict", "\n", NULL, 0); xmlNode *dict = add_child_to_plist(plist, "dict", "\n", NULL, 0);
...@@ -596,6 +658,14 @@ int lockdownd_start_SSL_session(lockdownd_client *control, const char *HostID) { ...@@ -596,6 +658,14 @@ int lockdownd_start_SSL_session(lockdownd_client *control, const char *HostID) {
} }
} }
/** gnutls callback for writing data to the iPhone.
*
* @param transport It's really the lockdownd client, but the method signature has to match
* @param buffer The data to send
* @param length The length of data to send in bytes
*
* @return The number of bytes sent
*/
ssize_t lockdownd_secuwrite(gnutls_transport_ptr_t transport, char *buffer, size_t length) { ssize_t lockdownd_secuwrite(gnutls_transport_ptr_t transport, char *buffer, size_t length) {
int bytes = 0; int bytes = 0;
lockdownd_client *control; lockdownd_client *control;
...@@ -615,6 +685,14 @@ ssize_t lockdownd_secuwrite(gnutls_transport_ptr_t transport, char *buffer, size ...@@ -615,6 +685,14 @@ ssize_t lockdownd_secuwrite(gnutls_transport_ptr_t transport, char *buffer, size
return bytes; return bytes;
} }
/** gnutls callback for reading data from the iPhone
*
* @param transport It's really the lockdownd client, but the method signature has to match
* @param buffer The buffer to store data in
* @param length The length of data to read in bytes
*
* @return The number of bytes read
*/
ssize_t lockdownd_securead(gnutls_transport_ptr_t transport, char *buffer, size_t length) { ssize_t lockdownd_securead(gnutls_transport_ptr_t transport, char *buffer, size_t length) {
int bytes = 0, pos_start_fill = 0; int bytes = 0, pos_start_fill = 0;
char *hackhackhack = NULL; char *hackhackhack = NULL;
...@@ -681,6 +759,13 @@ ssize_t lockdownd_securead(gnutls_transport_ptr_t transport, char *buffer, size_ ...@@ -681,6 +759,13 @@ ssize_t lockdownd_securead(gnutls_transport_ptr_t transport, char *buffer, size_
return bytes; return bytes;
} }
/** Command to start the desired service
*
* @param control The lockdownd client
* @param service The name of the service to start
*
* @return The port number the service was started on or 0 on failure.
*/
int lockdownd_start_service(lockdownd_client *control, const char *service) { int lockdownd_start_service(lockdownd_client *control, const char *service) {
if (!control) return 0; if (!control) return 0;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment