Tuesday, February 18, 2014

AeroGear iOS lib - 1.4.0 Release

Today, we are happy to announce the immediate availability of 1.4.0 of the AeroGear iOS library. The highlights of this release is the introduction of an Encrypted SQLite store in par with our encrypted In-Memory and Plist based stores, multipart upload API has been enhanced to support more data types apart from the regular NSURL object, and last but not least, an initial preview of our Oauth2 authorization adapter.

Let's dive in..

Encrypted SQLite store

If you have used the encrypted variants of plist and memory stores in our previous versions, you can easily switch to the encrypted SQLite variant by just setting the store type to ENCRYPTED_SQLITE. You can then use the regular Store protocol to read and write data, but this time the data are stored encrypted in an SQLite database. Let's see an example:

NSData *salt = [AGRandomGenerator randomBytes];
// set up crypto params configuration object
AGPassphraseCryptoConfig *config = [[AGPassphraseCryptoConfig alloc] init];
[config setSalt:salt];
[config setPassphrase:self.password.text];
// initialize the encryption service passing the config
id<AGEncryptionService> encService = [[AGKeyManager manager] keyService:config];
// access Store Manager
AGDataManager *manager = [AGDataManager manager];
// create store
store = [manager store:^(id<AGStoreConfig> config) {
    [config setName:@"CredentialsStorage"];
    [config setType:@"ENCRYPTED_SQLITE"];
    [config setEncryptionService:encService];
// ok time to attempt reading..
NSArray *data = [store readAll])
if (data)
    // decryption succeeded!

If you are not familiar with the security API, you can find detailed description in our Cryptography support guide. Further, you can also try our Crypto Cookbook demo that stores your passwords encrypted using either a plist or an sqlite backend.

Enhanced Multipart upload

In the previous version of the library, multipart upload was supported by the mean of attaching an NSURL object on the request that pointed to a local file. Although this method is still supported, we deprecated in favour of being more flexible on the data types that can be attached. Let's see an example usage:

// a multipart that contains a file
NSURL *file1 = [NSURL fileURLWithPath:@"path-to-the-a-local-file"];
AGFilePart *filePart = [[AGFilePart alloc]initWithFileURL:file1 name:@"myfile"];

// a multipart that contains an NSData object
NSData *data1 = [@"Lorem ipsum dolor sit amet.." dataUsingEncoding:NSUTF8StringEncoding];
AGFileDataPart *dataPart = [[AGFileDataPart alloc] initWithFileData:data1 
                                                            fileName:@"data1.txt" mimeType:@"text/plain"];

// set up payload
NSDictionary *dict = @{@"somekey": @"somevalue", 
                       @"another_key": @"some_other_key",

// set an (optional) progress block
[[apiClient uploadPipe] setUploadProgressBlock:^(NSUInteger bytesWritten, long long totalBytesWritten, long long totalBytesExpectedToWrite) {
    NSLog(@"UPLOADPIPE Sent bytesWritten=%d totalBytesWritten=%qi of totalBytesExpectedToWrite=%qi bytes", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);

// upload data
[[apiClient uploadPipe] save:dict success:^(id responseObject) {
    NSLog(@"Successfully uploaded!");

} failure:^(NSError *error) {
    NSLog(@"An error has occured during upload! \n%@", error);

As you can see from the example, we introduced new classes to encapsulate the different data types that can be attached on the request. An AGFilePart that can point to local NSURL objects, an AGFileDataPart that can be initialized from an NSData object directly and (not shown) an AGStreamPart that can be initialized from an NSInputStream.

OAuth2 Authorization

New to this release is the introduction of an OAuth2 adapter that will allow you to authorize against OAuth2 protected providers. Let's see an example usage that fetches the list of files residing in your Google Drive:

NSURL* serverURL = [NSURL URLWithString:"@"https://www.googleapis.com/drive/v2"];  
AGPipeline* googleFiles = [AGPipeline pipelineWithBaseURL:serverURL];  

AGAuthorizer* authorizer = [AGAuthorizer authorizer];  

_restAuthzModule = [authorizer authz:^(id<AGAuthzConfig> config) {              
    config.name = @"restAuthMod";  
    config.baseURL = [[NSURL alloc] initWithString:@"https://accounts.google.com"];  
    config.authzEndpoint = @"/o/oauth2/auth";  
    config.accessTokenEndpoint = @"/o/oauth2/token";  
    config.clientId = @"XXXXX";  
    config.redirectURL = @"org.aerogear.GoogleDrive:/oauth2Callback";  
    config.scopes = @[@"https://www.googleapis.com/auth/drive"];  

[_restAuthzModule requestAccessSuccess:^(id object) {                           
    id<AGPipe> files = [googleFiles pipe:^(id<AGPipeConfig> config) {       
        [config setName:@"files"];  
        [config setAuthzModule:authzModule];                                        
    [files read:^(id responseObject) {                                          
        // responseObject contains the list of files
    } failure:^(NSError *error) {  
        // when an error occurs... at least log it to the console..  
        NSLog(@"Read: An error occured! \n%@", error);  

} failure:^(NSError *error) {  

My friend Corinne has already written an excellent two-part (Part1 | Part2) series about the usage of the OAuth2 adapter and I strongly suggest you to visit her blog to learn more. You can also try our Cookbook demos, GoogleDrive and Shoot that go against Google Drive to fetch and store files.

As a final note, this release marks the end of the support of iOS 5/6 versions. Work is under-way to remove any hooks that were made to cater for bugs on those versions and we will focus our efforts exclusively on iOS 7 going forward.

So go ahead and give the release a spin. Download and explore our Cookbook demos, install the Xcode template on your IDE to easily get started, play and have fun!  We will be happy to hear your thoughts, suggestions and ways to improve it better. Join our mailing list, hangout on our #aerogear IRC channel and better, file us bugs!