SeaCat trial for iOS on Mac OS X

This blog entry is meant to help you to start using SeaCat component on your Xcode iOS development environment. It contains instructions how to install and configure SeaCat gateway and how to integrate SeaCat client into your iOS application.

Introduction

There are two main SeaCat components:

• SeaCat gateway: the application for Mac OS X
• SeaCat client: the framework for iOS

SeaCat gateway is a secure gate to the restricted network. It allows access only to selected HTTP hosts and prevents exposure of others. It also secures communication with SeaCat clients that are typically in the Internet.

SeaCat client becomes part of said mobile application and provides secured channel to SeaCat gateway and to target hosts in the restricted network. It ensures mutual security of the connection and transferred data.

SeaCat trial is simulating this environment on single piece of hardware (Mac). Mobile application with included SeaCat client is running in the iOS simulator and SeaCat gateway is running on the same machine. You also need a HTTP server that provides a content. Mac OS X built-in HTTP Apache Server is perfectly fine however you can of course use any other HTTP server (e.g. Node.js, TomCat, Flask etc.).

Note: HTTP server is called the host in a SeaCat environment and there can be more than one host in a SeaCat configuration.

Download

Trial pack can be downloaded from here. Once downloaded, unpack the archive into your Download folder or any other temporary location.

Structure of the download folder is as follows:

/SeaCat_Trial_OSX_iOS
    /SeaCatClientTrial.framework
    /SeaCatGateway
    LICENSE.txt
    README.txt
    VERSION

Installation of SeaCat gateway

Simply copy SeaCatGateway folder from downloaded archive to your preferred location e.g to your Home folder (to ~/SeaCatGateway/) or Documents folder (~/Documents/SeaCatGateway/).

To start gateway, open Terminal and enter following two commands:

cd ~/SeaCatGateway
./seacatd-trial

Application should give few output similar to this:

This means that installation is successful and the gateway is up and running. Please keep Terminal window open (you can hide or minimise it). The gateway can be stopped by pressing Ctrl-C when Terminal window is active or just by closing Terminal window.

Note: There are indeed advanced techniques how to launch and operate SeaCat gateway, e.g. as a Mac OS X service. Please refer to relevant Apple documentation or eventually to SeaCat blog.

Note: Preferred installation path on UNIX box is /opt/seacat. You can install SeaCat gateway trial into the same folder on a Mac, however you will need superuser privileges. Gateway doesn't need to be started under superuser account but please make sure that ./var folder (recursive) is writable by relevant user account.

Installation of SeaCat client

SeaCat client is an iOS framework that is meant to be added into a mobile application using Xcode.

Open Xcode with existing iOS project or alternatively use Xcode Welcome page to create fresh one (e.g. iOS Single View Application) and
select 'Frameworks' in Project Navigator in the left pane. Populate context menu by right click and select 'Add Files to …'

Go to unpacked SeaCat trial archive and choose SeaCatClientTrial.framework folder.
Then make sure that "Copy items into destination group's folder" checkbox is selected.
Finally press "Add".

As a result, SeaCatClientTrial framework is now added into list of frameworks and also to the list of libraries that are used in linking phase.

Integration of SeaCat client into your iOS app

You need to add few lines of code into your iOS project in order to properly enable SeaCat client.

Open your application delegate .m source file in Xcode editor, its file name ends with …AppDelegate.m.

Add #import <SeaCatClientTrial/SeaCat.h>" line just after another imports in the top of the source file.
Also add [SeaCatClient configure]; into didFinishLaunchingWithOptions: method just before final return.
Whole change should look like this:

…

#import "FooBarAppDelegate.h"
#import <SeaCatClientTrial/SeaCat.h> // <---- This line was added

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [SeaCatClient configure];  // <---- This line was added too

    return YES;
}

…

Now you should be able to build and run your application using standard Xcode commands. Press ⌘B to build it.

Note: There is repository on GitHub with code from this example.

Use of SeaCat trial

Congratulations! Your SeaCat trial is installed properly and you are ready for first steps with this product. Make sure that your SeaCat gateway is running when you work on your application.

All URLs that have scheme http or https and that host name ends with .seacat are intercepted by SeaCat and relevant HTTP request is transported securely to SeaCat gateway. The gateway then forwards such request to preconfigured host (HTTP server) to obtain response which is sent back to mobile application.

Check configuration of SeaCat gateway (SeaCatGateway/seacat-trial.conf), where a map between .seacat names and real target hosts is located.
Default trial configuration is:

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

This means that SeaCat client request for http://test.seacat/ is forwarded to http://127.0.0.1/ by SeaCat gateway. Any other .seacat host is unknown and requests will be rejected. .seacat. host names are virtual, there is no IP address available at client side.

Feel free to add more hosts or change existing entry. You need to always restart SeaCat gateway to propagate configuration changes.

Sample of Objective-C code that uses SeaCat:

NSURL * url = [NSURL URLWithString:@"https://test.seacat/index.html"];
NSError * err;
NSData * data = [NSData dataWithContentsOfURL:url options:0 error:&err];

Trial limitations

• Trial client library is available only for iOS simulator, you cannot build an application for actual iOS device using this trial version.
• Trial client expects SeaCat gateway running on localhost, therefore you need to run the gateway application on the same machine as iOS simulator.
• Trust of the gateway and the client is implicit. Full version evaluates trust of exchanged certificates thoroughly.
• Certificate signing procedure is simplified, basically CSR procedure is skipped.
• Trail is using TCP port 7443.

There is no time limit in use of trial version and you can use it for evaluation and for actual application development. The paid license is needed only for final release of your application.

Please note that security of trial version is limited. If you want to evaluate security of the SeaCat product, please let us first to get full version for such a testing.

SeaCat Tutorial Series

Please check also our tutorial series, it includes more examples of SeaCat, demonstrating important features of this product.

Feedback and questions

We are ready to listen to your comments and remarks, it helps us to shape SeaCat better. Please let us know!

Also if you have difficulties to in using SeaCat or you just want to ask for some details, contact us, we will more than happy to assist you.

Photo credit: Death to the stock photo