Client SDK Version 1.6.1
Welcome to the Ionic Security Client SDK for Obj-C!

Table of Contents

Introduction

The Client SDK for Obj-C is a client-side library provided by Ionic Security for the purpose of programming applications (standalone applications, services, plugins, etc.).

Version

The Client SDK version is 1.6.1

Module List

Error Handling

Error handling in the SDK is done with error codes. Any Ionic error code can be translated into a human-readable string via getErrorCodeString: (IonicAgentSDKError). Also, in all cases of error, the exact nature of the error is output through the SDK logger. Logging can easily be turned on (see IonicLog Overview).

Error codes are split up by SDK module:

Thread Safety

All objects and functions in the SDK are not thread-safe. The only exception to this is everything in the log module (IonicLog Overview).

For example, an IonicAgent object should never be used by more than one thread at any given time. It is recommended to create one IonicAgent object per thread when possible. Another possibility is to create a resource pool of IonicAgent objects that can be used ad-hoc by worker threads.

If an object is used simultaneously by multiple threads, then the behavior of the program becomes undefined and there will most likely be memory corruption and crashing.

Strings, Encodings, etc.

Without exception, all input and output strings provided to and from the SDK must be UTF-8 encoded. Doing so enables universal language interoperability with very little effort and with a very widely established Unicode format (UTF-8).

It should be noted that this rule is especially important when encrypting strings with any of the supported ciphers. This is because the resulting ciphertext may be decrypted in a completely different environment (OS and/or programming language) in which it is assumed that the decrypted plaintext is UTF-8 encoded. If the decrypted plaintext is not UTF-8 encoded, then problems may arise. For example, if decrypting to a string using the .NET SDK, the decrypted plaintext string must be transcoded to UTF-16 since that is the universal string encoding for .NET. The transcoding operation will fail if the original plaintext string was not UTF-8 encoded.

Logging

The SDK supports highly configurable logging that can be very useful when troubleshooting problems, auditing the activities of an application, etc. See IonicLog Overview for extensive documentation on this module.

Simple Code Examples

Documentation is great, but where is the code? Each module overview above (Module List) contains code samples to help get you going, but here is some code that is worth a thousand words.

Encrypting a file:

#import <IonicAgentSDK/IonicAgentSDK.h>
int main(int argc, const char * argv[])
{
NSError * error = nil;
// set up a simple logger that writes to a file in append mode and
// only emits messages with INFO severity and above
IonicLogBase * pLogger = [[IonicLogFactory getSingleton] createSimple:@"MyApplication.log" appendFile:YES severityLevel:IonicLogInfoSeverity];
// create an agent and initialize it using all defaults
IonicAgent * agent = [[IonicAgent alloc] initWithDefaults:&error];
// check for initialization error
if (error)
{
IonicLogF_Error(@"MyApplicationChannel", @"Failed to initialize agent object, error code = %d.", error.code);
return (int)error.code;
}
// create a file cipher which will use our agent for secure communication
// with Ionic API servers
IonicFileCryptoCipherAuto * fileCipher = [[IonicFileCryptoCipherAuto alloc] initWithAgent:agent];
// encrypt a sensitive file in place
[fileCipher encryptFileAtPath:@"MySensitiveFile.docx" error:&error];
if (error)
{
IonicLogF_Error(@"MyApplicationChannel", @"Failed to encrypt a file, error code = %d.", error.code);
return (int)error.code;
}
// success!
}

Requesting a key and encrypting a string:

#import <IonicAgentSDK/IonicAgentSDK.h>
int main(int argc, const char * argv[])
{
NSError * error = nil;
// set up a simple logger that writes to a file in append mode and
// only emits messages with INFO severity and above
IonicLogBase * pLogger = [[IonicLogFactory getSingleton] createSimple:@"MyApplication.log" appendFile:YES severityLevel:IonicLogInfoSeverity];
// create an agent and initialize it using all defaults
IonicAgent * agent = [[IonicAgent alloc] initWithDefaults:&error];
// check for initialization error
if (error)
{
IonicLogF_Error(@"MyApplicationChannel", @"Failed to initialize agent object, error code = %d.", error.code);
return (int)error.code;
}
// set up some possibly useful key attributes to associate with our data protection key
NSDictionary * attributes = @{
@"classification": @[@"confidential"],
@"contains": @[@"ssn", @"financials"]
};
// attempt to create the key
IonicAgentCreateKeysResponse * response = [agent createKeyWithAttributes:attributes error:&error];
if (error)
{
IonicLogF_Error(@"MyApplicationChannel", @"Failed to create a data protection key, error code = %d.", error.code);
return (int)error.code;
}
// make a variable for the key we just created, for convenience
IonicAgentCreateKeysResponseKey * createdKey = [response.keys firstObject];
// create an AES GCM cipher and configure it with our newly created data protection key
[cipher setKey:createdKey.key error:nil];
[cipher setAuthData:[@"My Custom ADATA" dataUsingEncoding:NSUTF8StringEncoding]];
// encrypt a sensitive string
NSData * encryptedBytes = [cipher encryptText:@"MyPassw0rd1s_VerySensitive!" error:&error];
if (error)
{
IonicLogF_Error(@"MyApplicationChannel", @"Failed to encrypt a sensitive string, error code = %d.", error.code);
return (int)error.code;
}
// success!
}