Read Me About TLSTool |
===================== |
1.0 |
|
TLSTool is a sample that shows how to implement Transport Layer Security (TLS), and its predecessor, Secure Sockets Layer (SSL), using the NSStream API. TLSTool demonstrates TLS in both client and server mode. |
|
TLSTool can also be used to explore TLS interactively, much like OpenSSL's s_client and s_server subcommands. However, because TLSTool uses the OS's built-in TLS stack, it will behave more like other built-in apps that use TLS (Mail, Safari, and so on). |
|
TLSTool requires OS X 10.9 but the core TLS techniques it shows are compatible with OS X back to at least OS X 10.4 (and all versions of iOS for that matter). |
|
Packing List |
------------ |
The sample contains the following items: |
|
o Read Me About TLSTool.txt -- This file. |
|
o TLSTool.xcodeproj -- An Xcode project for the program. |
|
o build -- A pre-built binary. |
|
o TLSTool -- A directory containing: |
|
- main.m -- The command line tool main. |
|
- TLSToolClient.{h,m} -- Core of the client implementation. |
|
- TLSToolServer.{h,m} -- Core of the server implementation. |
|
- TLSToolCommon.{h,m} -- Code shared between the client and server. |
|
- QNetworkAdditions.{h,m} -- A compatibility shim for certain networking APIs. |
|
- QHex.{h,m} -- Hex dump utilities. |
|
Using the Sample |
---------------- |
It's easy to use TLSTool to run a simple TLS client test. For example, to fetch the URL <https://apple.com/>: |
|
1. In Terminal, change into the sample code directory. |
|
$ cd ~/Downloads/TLSTool |
|
2. Run the tool as shown below: |
|
$ build/Debug/TLSTool s_client -connect apple.com:443 |
|
* input stream did open |
* output stream did open |
* output stream has space |
* trust result: unspecified |
* certificate subjects: |
* 0 apple.com |
* 1 Entrust Certification Authority - L1C |
* 2 Entrust.net Certification Authority (2048) |
* 3 Entrust.net Secure Server Certification Authority |
|
Note: The lines prefixed by "*" are debugging information from the tool. The above shows the chain of trust leading from "apple.com" to the trust CA root certificate "Entrust.net Secure Server Certification Authority". |
|
3. Enter the text below, hitting return after each line and return twice at the end. |
|
GET / HTTP/1.1 |
Host: apple.com |
Connection: close |
|
The tool will print the server's response (see below) and then quit once the server closes the connection. |
|
* output stream has space |
* input stream has bytes |
HTTP/1.1 301 MOVED PERMANENTLY |
Server: |
Date: |
Referer: |
Location: https://www.apple.com/ |
Content-type: text/html |
Connection: close |
|
* input stream has bytes |
* input stream has bytes |
* input stream end |
* close |
|
* * * |
|
IMPORTANT: To test the server code you will need a TLS server digital identity in your keychain. If you don't have one handy, you can create one using the instructions in Technote 2326 "Creating Certificates for TLS Testing". |
|
</RU/OSX/technotes/tn2326/_index.html> |
|
In the following example the TLS server digital identity is called "guy-smiley.local." and it's issued by the "QSecure CA" certificate authority. |
|
To test the server code: |
|
1. In Terminal, open a client window and a server window and change into the sample code directory in each. |
|
server$ cd ~/Downloads/TLSTool |
|
client$ cd ~/Downloads/TLSTool |
|
2. In the server window, run the tool as shown below: |
|
server$ build/Debug/TLSTool s_server -cert guy-smiley.local |
* server identity: guy-smiley.local |
* server did start |
|
Note: If you don't supply a port number (via the "-accept" command line argument) the server listens on port 4433. |
|
3. In the client window, run the tool as shown below: |
|
client$ build/Debug/TLSTool s_client -noverify |
* input stream did open |
* output stream did open |
* output stream has space |
* trust result: recoverable trust failure |
* certificate subjects: |
* 0 guy-smiley.local |
* 1 QSecure CA |
|
Note: If you don't supply a connection address (via the "-connect" command line argument) the client connects to localhost:4433. |
|
Note: The "-noverify" option disables TLS server trust evaluation, allowing the connection to succeed even though the server's certificate is not trusted by the system. If I configured the system to trust the "QSecure CA" root certificate it would not be necessary. |
|
In the server window you'll see: |
|
* input stream did open |
* output stream did open |
* output stream has space |
* no trust |
|
4. Once things are connected like this you can type text in the server window and it'll show up in the client window and vice versa. |
|
5. Enter control-D in either window to close the connection. |
|
* * * |
|
The tool has lots of other options. Run the command below to see the usage: |
|
$ build/Debug/TLSTool -? |
... |
|
Building the Sample |
------------------- |
The sample was built using Xcode 5.1.1 on OS X 10.9.4 with the OS X 10.9 SDK. You should be able to just open the project and choose Product > Build. |
|
How it Works |
------------ |
The project contains lots of networking code that's the same as any other NSStream-based networking app. You can see the code in TLSToolCommon but you'd probably be better off looking at other, simpler samples, including: |
|
o SimpleNetworkStreams |
|
</RU/iOS/#samplecode/SimpleNetworkStreams/> |
|
o WiTap |
|
</RU/iOS/#samplecode/WiTap/> |
|
o PictureSharing |
|
</RU/OSX/#samplecode/PictureSharing/> |
|
o RemoteCurrency |
|
</RU/OSX/#samplecode/RemoteCurrency/> |
|
If you're interested in TLS you should focus on the TLSToolClient and TLSToolServer classes, each of which is quite small. Specifically: |
|
o -[TLSToolClient run] shows how to set up a stream pair for TLS client operation |
|
o -[TLSToolServer startConnectionWithInputStream:outputStream:] shows how to set up a stream pair for TLS server operation |
|
Caveats |
------- |
The tool's command line arguments are somewhat compatible with OpenSSL's s_client and s_server subcommands. This compatibility layer is wafer thin; there are lots of options that just aren't implemented, and some options that don't work the same way as OpenSSL. For example, the OpenSSL s_client subcommand disables TLS server trust evaluation by default but TLSTool leaves it enabled because disabling it is, in general, a bad idea. |
|
The goal of TLSTool is not to provide 100% compatibility with OpenSSL's commands, but rather to a) be a reasonable code sample, and b) provide basic compatibility to preserve 'muscle memory'. Improving the latter would undermine the former. |
|
Feedback |
-------- |
If you find any problems with this sample, or you'd like to suggest improvements, please file a bug against it. |
|
<http://developer.apple.com/bugreporter/> |
|
Version History |
--------------- |
1.0 (Aug 2014) was the first shipping version. |
|
Share and Enjoy |
|
Apple Developer Technical Support |
Core OS/Hardware |
|
15 Aug 2014 |
