SeaCat trial for iOS on Mac OS X

Guy and ios smartphone

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

High level diagram

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:
SeaCat gateway running in terminal

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 …'

SeaCat client installation using Drag and Drop

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".

SeaCat client installation using Drag and Drop

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.

SeaCat client installation using Drag and Drop

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 &lt;SeaCatClientTrial/SeaCat.h&gt; // &lt;---- This line was added

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [SeaCatClient configure];  // &lt;---- 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:&amp;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




You Might Be Interested in Reading These Articles

A beginner-friendly intro to the Correlator for effective cybersecurity detection

At TeskaLabs, we know that a cybersecurity system is only as effective as its ability to detect threats. That's why we developed a powerful tool that will prove essential in your arsenal: the Correlator.

Continue reading ...

security tech

Published on March 15, 2024

SeaCat Mobile Secure Gateways' Performance Test

We decided to perform this test to validate our architectural, design and implementation decisions in regards to SeaCat performance. Our goal was to build the best-in-class product using the most advanced techniques to deliver highest possible throughput yet not compromising the security of the communication. Results of the test have been fed back into our development team to improve further overall performance characteristics of the solution.

Continue reading ...

tech

Published on July 21, 2014

What Is Mobile Application Containerization or Wrapper, and Why It Needs to Go?

Containerization is an alternative for full machine virtualization. You probably know well-known containerization technology from Docker or Rocket. However, this article addresses the pros and cons of mobile “containerization” or wrapper used to isolate the mobile app from the mobile operating system or other applications installed on the same device. These type of “containerization” work in a different way.

Continue reading ...

tech security

Published on September 27, 2016