SeaCat Tutorial - Chapter 1: Hello World (iOS)

Foreword

This is the first practical tutorial in our tutorial series to demonstrate the strength and capabilities of SeaCat secure access solution. Our goal is to develop several sample applications and uncover the best practices you might be interested in.

In this text we create a simple Node.js host and an iOS app which reads a JSON response generated by that host. As our motivation is mainly security, we also incorporate SeaCat to enable fast and convenient secure communication between our iOS client and Node.js host.

Requirements

Before we start, please make sure you have installed following software/packages in your development environment (assuming you have Mac OS X):

Creating Node.js host

The preparation a basic Node.js host is very straightforward. You can get things done in just few lines of code. In your favorite text editor write following lines of code (or download HelloWorldNodeHost.js from GitHub):

var http = require('http');

var json_content = {
    message: "Hello world"  
};

http.createServer(function(request, response){
    response.writeHead(200, {'Content-Type': 'text/json'});
    response.write(JSON.stringify(json_content));
    response.end()
}).listen(1337, '127.0.0.1');

console.log("Running Node.js host...");

This is very simple HTTP REST responder that emits simple JSON object for any HTTP request to http://localhost:1337/.

Save this code to a JavaScript file (HelloWorldNodeHost.js in our case) and run it by typing node fileName.js in terminal (node HelloWorldNodeHost.js in our case). If you are successful, you will see an output similar to this:

Node.js host running in terminal

To test if everything runs correctly, please open another terminal and type curl http://localhost:1337; echo there (echo stands for adding a new line character at the of output stream).

Node.js host running in terminal

The response should be: {"message":"Hello world"} as shown in the picture above. Your host is ready. Keep it running.

SeaCat Gateway Configuration

Another important step in our solution is to configure the SeaCat Gateway which helps to handle the communication between your Node.js host and your iOS application.

Download SeaCat trial installation package and unpack the package by typing tar xjvf SeaCat_Trial_OSX_iOS_14.12.tar.bz2 in terminal.

Unpacking the content of SeaCat installer

Next step is the final configuration. In unpacked structure check the file seacat-trial.conf in SeaCat_Trial_OSX_iOS/SeaCatGateway directory. The default configuration have following structure:

[host:test]
uri=http://127.0.0.1/

Change the configuration as following (our host listens on port 1337):

[host:nodejshost]
uri=http://127.0.0.1:1337/

You can also download the updated version of seacat-trial.conf from GitHub.

Once you save the changes in seacat-trial.conf, run the SeaCat Gateway by typing ./seacatd-trial in terminal window (in the same directory as the config file). If you see the output similar to following, your SeaCat Gateway is set correctly.

Output generated by Sea Cat Gatewat

Keep both Node.js host and SeaCat Gateway running.

iOS Application

Last step in this journey is to write a iOS application which reads the JSON response from the SeaCat Gateway which communicate with the Node.js host via SeaCat Gateway. This application will use SeaCat Client to facilitate this communication.

Open Xcode and create a new iOS application. From the template list select Single View Application and click on the Next button.

New Project in Xcode

Next pane contains several fields which are important for the app identification. Type HelloWorld to Product Name and Class Prefix fields. How you fill other two fields is completely up to you. For the purpose of our tutorial fields Organization name and Company Identifier are unrelated.

New Project in Xcode

Click on the Next button again and Xcode creates initial application structure on the disk. Your environment will look like this:

Initial screen in Xcode

Integration of SeaCat client

As the next and important step, it is necessary to add SeaCat client into your application. This process is very simple. In Finder open SeaCat_Trial_OSX_iOS folder and drag SeaCatClientTrial.framework object into Frameworks directory in Xcode.

Initial screen in Xcode

When next screen appear, the only thing you have to make sure is to have Destination option checked. This will help to copy the framework into project structure.

SeaCat framework listed

Once you click on Finish button, you will see SeaCatClientTrial.framework among other ones.

SeaCat framework listed

Adding interactivity

To incorporate the framework into the structure of our app is not enough, we also have to connect the SeaCatClient with our app code. To do that is very straightforward. Just click on HelloWorldAppDelegate.m file in the Xcode project structure.

Delegate default

And change the code from the default:

#import "HelloWorldAppDelegate.h"

@implementation HelloWorldAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Override point for customization after application launch.
    return YES;
}

to one where SeaCat is incorporated:

#import "HelloWorldAppDelegate.h"
#import <SeaCatClientTrial/SeaCat.h>

@implementation HelloWorldAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions: (NSDictionary *)launchOptions
{
    /* This method finalises SeaCat client initial configuration. It also ensures that client is integrated with Core Foundation URL Loading System (check Apple URLLoadingSystem in documentation for more information). So all URL requests are intercepted, analysed and eventually processed by SeaCat gateway instead of common HTTP transport. */

    [SeaCatClient configure];

    return YES;
}

Delegate after update

The more information about URL Loading System is available in official documentation.

Designing an User Interface

Once you finish the previous steps, open Main.storyboard from the project structure and add UILabel component from the Object Library pane to Hello World View Controller container in Main.storyboard.

Adding label

Next step in our development is to connect the label from the Interface Builder (Main.storyboard) with the code (HelloWorldViewController.h and HelloWorldViewController.m in our case).

In Main.storyboard show the Assistant Editor and make sure you see HelloWorldViewController.h file in the code part.

Xcode assistant editor

Click on UILabel object (placed in Hello World View Controller container), hold CTRL key on your keyboard and drag the cursor into HelloWorldViewController.h

Xcode assistant editor

If you did everything correctly, you will see a small dialog. Make sure the Connection is set Outlet and Name to result. Once your settings is done, click on Connect button.

Xcode assistant editor

Following line of code will be added to your HelloWorldViewController.h

@property (weak, nonatomic) IBOutlet UILabel *result;

You can also change the size of the Label in Main.storyboard. Your final output will be much better.

Xcode assistant editor

URL Request to host

Add following code at the end of the HelloWorldViewController.m (before the final @end):

- (void)fetchGreeting
{
    /* Following two lines represent fairly standard URL request mechanism provided by Apple Core Foundation. SeaCat functionality is triggered by '.seacat' extension of URL host (see https://nodejshost.seacat/). Such a request is intercepted by SeaCat client, forwarded in secure way to SeaCat gateway and consequently to 'nodejshost' host.*/

    NSURL *url = [NSURL URLWithString:@"https://nodejshost.seacat/"];
    NSURLRequest *request = [NSURLRequest requestWithURL:url];

   /* Parsing  of response in JSON format. */

    [NSURLConnection sendAsynchronousRequest: request
        queue:[NSOperationQueue mainQueue]
        completionHandler:^(NSURLResponse *response, NSData *data,NSError *connectionError)
    {
        if (data.length > 0 && connectionError == nil)
        {
            NSDictionary *greeting = [NSJSONSerialization JSONObjectWithData:data options: 0 error:NULL];
            self.result.text = [greeting objectForKey:@"message"];
        }
    }];
}

And we finish our effort by adding [self fetchGreeting]; to -(void)viewDidLoad method (in HelloWorldViewController.m)

- (void)viewDidLoad
{
    [super viewDidLoad];
    [self fetchGreeting];
}

We are done

Now you can run the app in simulator.

Xcode simulator

And see Hello World message in your label.

Xcode simulator

Pretty cool, isn't it? With a minimal effort we built a functional and secure application with using of SeaCat architecture.

All source codes from this example are available in GitHub.
Please visit also other blog entries from SeaCat Tutorial series.

SeaCat iOS tutorials in this series:

  1. Chapter 1: Hello World
  2. Chapter 2: Simple Post
  3. Chapter 3: Introduction to REST Integration
  4. Chapter 4: Using MongoDB with REST Integration
  5. Chapter 5: Using Parse.com with REST Integration

About the Author

Ales Teska

TeskaLabs’ founder and CEO, Ales Teska, is a driven innovator who proactively builds things and comes up with solutions to solve practical IT problems.




You Might Be Interested in Reading These Articles

What’s The Difference Between Seacat and VPN?

One of the most common questions people asked us is if SeaCat some kind of a VPN? It's not. Virtual Private Network (VPN) extends a private network across a public network, providing secure connectivity from/to a mobile device. Every application on this device, thus now has access to the private network through the channel opened by VPN. This is safe up to a certain level because it is almost impossible to ensure the integrity of every application on the devices. Especially now when there are apps for everything, and users can download them from Google Play and the Apple store.

Continue reading ...

tech

Published on November 25, 2014

SP-Lang: Category theory in the wild

We recently encountered several interesting problems that demonstrate how seemingly abstract category theory finds its practical applications and helps us solve these problems sustainably.

Continue reading ...

splang tech

Published on August 20, 2022

Entangled ways of product development in the area of cybersecurity #1 - Asynchronous or parallel?

I started working at TeskaLabs at the beginning of autumn 2017 as a student at the Faculty of Information Technology of CTU. In the job advertisement, I was particularly interested in the fact that it is a small, product-based company that does not focus on just one technology or one programming language.

Continue reading ...

development tech premek

Published on November 15, 2022