-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #26 from vapor/1.0
1.0
- Loading branch information
Showing
3 changed files
with
16 additions
and
112 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,120 +1,25 @@ | ||
| # Transport Layer Security (TLS/SSL) for Swift | ||
|
|
||
| > Transport Layer Security (TLS) is the successor to Secure Socket Layer 3.0 (SSL). SSL 3.0 was deprecated in June 2015. | ||
| > https://tools.ietf.org/html/rfc7568 | ||
|  | ||
| [](https://travis-ci.org/vapor/tls) | ||
| [](https://circleci.com/gh/vapor/tls) | ||
|  | ||
| [](https://travis-ci.org/vapor/tls) | ||
| [](https://circleci.com/gh/vapor/tls) | ||
| [](https://codecov.io/gh/vapor/tls) | ||
| [](https://codebeat.co/projects/github-com-vapor-tls) | ||
| [](http://vapor.team) | ||
|
|
||
| A Swift wrapper for Transport Layer Security (TLS/SSL) using OpenSSL. | ||
|
|
||
| - [x] Swifty Interface | ||
| - [x] Client and Server | ||
| - [x] Tested | ||
|
|
||
| ## Examples | ||
|
|
||
| The examples below assume you already have a socket library and you want to add TLS. If you do not already have a socket library, check out [Socks](https://github.com/czechboy0/Socks) by Honza Dvorsky. | ||
|
|
||
| There is an add-on for Socks called [SecretSocks](https://github.com/czechboy0/SecretSocks) that includes this TLS library and provides a convenient `makeSecret()` method for all Socks' sockets. | ||
|
|
||
| If you are using a different socket library, no need to worry. You only need access to the socket's file descriptor to use this package. | ||
|
|
||
| ```swift | ||
| import TLS | ||
|
|
||
| let socket: MyUnsecureSocket | ||
|
|
||
| // Create an unsecure socket | ||
| // and grab its file descriptor. | ||
| // ... | ||
|
|
||
| let descriptor: Int32 = socket.mySocketDescriptor | ||
| ``` | ||
|
|
||
| Now that you have the descriptor, let's add TLS. | ||
|
|
||
| ### Client | ||
|
|
||
| This adds a Transport Security Layer for interacting with a server from a client. No certificates are required to be a client. | ||
|
|
||
| ```swift | ||
| let secureSocket = try TLS.Socket(mode: .client, descriptor: descriptor) | ||
|
|
||
| try secureSocket.connect() | ||
| ``` | ||
|
|
||
| Here a context is created. You should hold on to this context if you intend to create multiple sockets. Your socket `descriptor` is then used with the `context` to create an `TLS.Socket`. | ||
|
|
||
| The call to `connect()` creates the connection to the server to start sending and receiving data. This should be called **after** the unsecure socket has called its version of `connect()`. | ||
|
|
||
| ### Server | ||
|
|
||
| This adds a Transport Security Layer for interacting with a client from a server. Setting up a server requires certificates. | ||
|
|
||
| ```swift | ||
| let context = try TLS.Context(mode: .server) | ||
|
|
||
| let secureSocket = try TLS.Socket(context: context, descriptor: descriptor, certificates: .files( | ||
| certificateFile: "./Certs/cert.pem", | ||
| privateKeyFile: "./Certs/key.pem", | ||
| signature: .selfSigned | ||
| )) | ||
|
|
||
| try secureSocket.accept() | ||
| ``` | ||
|
|
||
| Here a context is created. You should hold on to this context if you intend to create multiple sockets. Your socket `descriptor` is then used with the `context` to create an `TLS.Socket`. | ||
|
|
||
| The call to `accept()` accepts the connection and performs the TLS handshake with the client. This should be called **after** the unsecure socket has called its version of `accept()`. | ||
|
|
||
| ### Sending / Receiving | ||
|
|
||
| You can now send and receive data through the new secure socket. | ||
|
|
||
| ```swift | ||
| try secureSocket.send([0x00, 0x01, 0x02]) | ||
| let data = try secureSocket.receive(max: 3) | ||
| ``` | ||
|
|
||
| ### Certificates | ||
|
|
||
| The `Certificates` enum lets you supply the appropriate certificates for your TLS-enabled server. | ||
|
|
||
| ```swift | ||
| public enum Certificates { | ||
| case none | ||
| case files(certificateFile: String, privateKeyFile: String, signature: Certificate.Signature) | ||
| case chain(chainFile: String, signature: Certificate.Signature) | ||
| } | ||
|
|
||
| public enum Certificate.Signature { | ||
| case selfSigned | ||
| case signedFile(caCertificateFile: String) | ||
| case signedDirectory(caCertificateDirectory: String) | ||
| } | ||
| ``` | ||
|
|
||
| ### Errors | ||
|
|
||
| The `Error` enum comprises all errors that can be thrown from this module. The `String` in all of the cases is a readable error message from LibreSSL. | ||
|
|
||
| ## Using with Xcode | ||
|
|
||
| Swift Package Manager will automatically build this project correctly, but when using with Xcode, you will need to add a setting to your Xcode project file: | ||
| > Transport Layer Security (TLS) is the successor to Secure Socket Layer 3.0 (SSL). SSL 3.0 was deprecated in June 2015. | ||
| > https://tools.ietf.org/html/rfc7568 | ||
| Under Project > Build Settings > Library Search Paths, add: | ||
| ## 📖 Documentation | ||
|
|
||
| ``` | ||
| $(PROJECT_DIR)/** | ||
| ``` | ||
| Visit the Vapor web framework's [documentation](http://docs.vapor.codes) for instructions on how to use this package. | ||
|
|
||
| ## Vapor | ||
| ## 💧 Community | ||
|
|
||
| This wrapper was created to power [Vapor](https://github.com/vapor/vapor), an Web Framework for Swift. | ||
| Join the welcoming community of fellow Vapor developers in [slack](http://vapor.team). | ||
|
|
||
| ## Author | ||
| ## 🔧 Compatibility | ||
|
|
||
| Created by [Tanner Nelson](https://github.com/tannernelson). | ||
| This package has been tested on macOS and Ubuntu. |