{"id":13465984,"url":"https://github.com/Kitura/BlueSSLService","last_synced_at":"2025-03-25T21:30:59.653Z","repository":{"id":46598711,"uuid":"59753581","full_name":"Kitura/BlueSSLService","owner":"Kitura","description":"SSL/TLS Add-in for BlueSocket using Secure Transport and OpenSSL","archived":false,"fork":false,"pushed_at":"2022-10-06T00:44:42.000Z","size":382,"stargazers_count":97,"open_issues_count":18,"forks_count":51,"subscribers_count":31,"default_branch":"master","last_synced_at":"2024-10-29T19:14:04.238Z","etag":null,"topics":["linux","macos","networking","security","socket","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kitura.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-26T13:43:43.000Z","updated_at":"2024-09-11T15:37:36.000Z","dependencies_parsed_at":"2022-08-21T01:50:54.646Z","dependency_job_id":null,"html_url":"https://github.com/Kitura/BlueSSLService","commit_stats":null,"previous_names":["ibm-swift/bluesslservice"],"tags_count":243,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitura%2FBlueSSLService","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitura%2FBlueSSLService/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitura%2FBlueSSLService/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitura%2FBlueSSLService/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kitura","download_url":"https://codeload.github.com/Kitura/BlueSSLService/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245267511,"owners_count":20587458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","macos","networking","security","socket","swift"],"created_at":"2024-07-31T15:00:37.636Z","updated_at":"2025-03-25T21:30:59.398Z","avatar_url":"https://github.com/Kitura.png","language":"Swift","funding_links":[],"categories":["Libs","Network [🔝](#readme)","Swift"],"sub_categories":["Network"],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.kitura.io/packages.html#all\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/docs-kitura.io-1FBCE4.svg\" alt=\"APIDoc\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://travis-ci.org/Kitura/BlueSSLService\"\u003e\n    \u003cimg src=\"https://travis-ci.org/Kitura/BlueSSLService.svg?branch=master\" alt=\"Build Status - Master\"\u003e\n    \u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/os-macOS-green.svg?style=flat\" alt=\"macOS\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/os-iOS-green.svg?style=flat\" alt=\"iOS\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/os-linux-green.svg?style=flat\" alt=\"Linux\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-Apache2-blue.svg?style=flat\" alt=\"Apache 2\"\u003e\n    \u003ca href=\"http://swift-at-ibm-slack.mybluemix.net/\"\u003e\n    \u003cimg src=\"http://swift-at-ibm-slack.mybluemix.net/badge.svg\" alt=\"Slack Status\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# BlueSSLService\n\nSSL/TLS Add-in framework for [BlueSocket](https://github.com/Kitura/BlueSocket.git) in Swift using the Swift Package Manager. Works on supported Apple platforms (using Secure Transport) and on Linux (using OpenSSL).\n\n## Prerequisites\n\n### Swift\n\n* Swift Open Source `swift-5.2-RELEASE` toolchain (**Minimum REQUIRED for latest release**)\n* Swift Open Source `swift-5.5-RELEASE` toolchain (**Recommended**)\n* Swift toolchain included in *Xcode Version 11.0 or higher*.\n\nBlueSSLService version 2.0 and above supports Swift 5.2+.  See older versions of BlueSSLService for older versions of Swift.\n\n### macOS\n\n* macOS 10.14.6 (*Mojave*) or higher.\n* Xcode Version 11.0 or higher using one of the above toolchains.\n* Xcode Version 12.5 or higher using the included toolchain (*Recommended*).\n* Secure Transport is provided by macOS.\n\n### iOS\n\n* iOS 10.0 or higher\n* Xcode Version 11.0 or higher using one of the above toolchains.\n* Xcode Version 12.5 or higher using the included toolchain (*Recommended*).\n* Secure Transport is provided by iOS.\n\n### Linux\n\n* Ubuntu 16.04 (or 16.10 but only tested on 16.04) and 18.04.\n* One of the Swift Open Source toolchain listed above.\n* OpenSSL is provided by the distribution.  **Note:** 3.0.x and later releases of OpenSSL are supported.\n* The appropriate **libssl-dev** package is required to be installed when building.\n\n### Other Platforms\n\n* **BlueSSLService** is **NOT** supported on *watchOS* since POSIX/BSD/Darwin sockets are not supported on the actual device although they are supported in the simulator.\n* **BlueSSLService** should work on *tvOS* but has **NOT** been tested.\n\n*Note:* See `Package.swift` for details.\n\n## Build\n\nTo build `SSLService` from the command line:\n\n```\n% cd \u003cpath-to-clone\u003e\n% swift build\n```\n\n## Testing\n\nTo run the supplied unit tests for **SSLService** from the command line:\n\n```\n% cd \u003cpath-to-clone\u003e\n% swift build\n% swift test\n```\n\n## Using BlueSSLService\n\n### Before starting\n\nThe first you need to do is import both the `Socket` and `SSLService` frameworks.  This is done by the following:\n```swift\nimport Socket\nimport SSLService\n```\n\n### Creating the Configuration\n\nBoth clients and server require at a minimum the following configuration items:\n* CA Certficate (either `caCertificateFile` or `caCertificateDirPath`)\n* Application certificate (`certificateFilePath`)\n* Private Key file (`keyFilePath`)\n\n**or**\n\n* Certificate Chain File (`chainFilePath`)\n\n**or**, if using `self-signed` certificates:\n\n* Application certificate (`certificateFilePath`)\n* Private Key file (`keyFilePath`)\n\n**or**, if running on Linux (for now),\n\n* A string containing a *PEM formatted* certificate\n\n**or**, if running on macOS:\n\n* Certificate Chain File (`chainFilePath`) in **PKCS12** format\n\n**or**,\n\n* No certificate at all.\n\n**BlueSSLService** provides five ways to create a `Configuration` supporting the scenarios above.  Only the **last version is supported on Apple platforms.**  On Linux, **ALL** versions are supported.  This is due to the limits imposed on the current implementation of *Apple Secure Transport*.\n- `init()` - This API allows for the creation of *default* configuration.  This is equivalent to calling the next initializer without changing any parameters.\n- `init(withCipherSuite cipherSuite: String? = nil, clientAllowsSelfSignedCertificates: Bool = true)` - This API allows for the creation of configuration that does not contain a backing certificate or certificate chain.  You can optionally provide a *cipherSuite* and decide whether to allow, when in client mode, use of *self-signed certificates* by the server.\n- `init(withCACertificatePath caCertificateFilePath: String?, usingCertificateFile certificateFilePath: String?, withKeyFile keyFilePath: String? = nil, usingSelfSignedCerts selfSigned: Bool = true, cipherSuite: String? = nil)` - This API allows you to create a configuration using a self contained `Certificate Authority (CA)` file. The second parameter is the path to the `Certificate` file to be used by application to establish the connection.  The next parameter is the path to the `Private Key` file used by application corresponding to the `Public Key` in the `Certificate`. If you're using `self-signed certificates`, set the last parameter to true.\n- `init(withCACertificateDirectory caCertificateDirPath: String?, usingCertificateFile certificateFilePath: String?, withKeyFile keyFilePath: String? = nil, usingSelfSignedCerts selfSigned: Bool = true, cipherSuite: String? = nil)` - This API allows you to create a configuration using a directory of `Certificate Authority (CA)` files. These `CA` certificates **must** be hashed using the `Certificate Tool` provided by `OpenSSL`. The following parameters are identical to the previous API.\n- `init(withPEMCertificateString certificateString: String, usingSelfSignedCerts selfSigned: Bool = true, cipherSuite: String? = nil)` - This API used when supplying a PEM formatted certificate presented as a *String*. **NOTE: At present, this API is only available on Linux.**\n- `init(withChainFilePath chainFilePath: String? = nil, withPassword password: String? = nil, usingSelfSignedCerts selfSigned: Bool = true, clientAllowsSelfSignedCertificates: Bool = false, cipherSuite: String? = nil)` - This API allows you to create a configuration using a single `Certificate Chain File` (see note 2 below). Add an optional password (if required) using the third parameter. Set the third parameter to true if the certificates you are using are `self-signed`, otherwise set it to false. If configuring a client and you want that client to be able to connect to servers using `self-signed` certificates, set the fourth parameter to true. \n\n*Note 1:* All `Certificate` and `Private Key` files must be `PEM` format. If supplying a certificate via a `String`, it must be PEM formatted. \n\n*Note 2:* If using a certificate chain file, the certificates must be in `PEM` format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate `CA` certificates if applicable, and ending at the highest level (root) `CA`.\n\n*Note 3:* For the first two versions of the API, if your `Private key` is included in your certificate file, you can omit this parameter and the API will use the same file name as specified for the certificate file.\n\n*Note 4:* If you desire to customize the cipher suite used, you can do so by specifying the `cipherSuite` parameter when using one of the above initializers.  If not specified, the default value is set to `DEFAULT` on Linux. On macOS, setting of this parameter is currently not supported and attempting to set it will result in unpredictable results.  See the example below.\n\n*Note 5:* If you're running on macOS, you must use the last form of `init` for the `Configuration` and provide a certificate chain file in `PKCS12` format, supplying a `password` if needed.\n\n#### Example\n\nThe following illustrates creating a configuration (on *Linux*) using the second form of the API above using a self-signed certificate file as the key file and not supplying a certificate chain file.  It also illustrates setting the cipher suite to `ALL` from the default:\n```swift\nimport SSLService\n\n...\n\nlet myCertPath = \"/opt/myApp/config/myCertificate.pem\"\nlet myKeyPath = \"/opt/myApp/config/myKeyFile.pem\"\n\nlet myConfig = SSLService.Configuration(withCACertificateDirectory: nil, usingCertificateFile: myCertPath, withKeyFile: myKeyFile)\n\nmyConfig.cipherSuite = \"ALL\"\n\n...\n\n```\n*Note:* This example takes advantage of the `default` parameters available on the `SSLService.Configuration.init` function. Also, changing of the `cipher suite` on *macOS* is currently not supported.\n\n### Creating and using the SSLService\n\nThe following API is used to create the `SSLService`:\n- `init?(usingConfiguration config: Configuration) throws` - This will create an instance of the `SSLService` using a previously created `Configuration`.\n\nOnce the `SSLService` is created, it can applied to a previously created `Socket` instance that's just been created. This needs to be done **before** using the `Socket`. The following code snippet illustrates how to do this (again using *Linux*).  *Note: Exception handling omitted for brevity.*\n\n```swift\n\nimport Socket\nimport SSLService\n\n...\n\n// Create the configuration...\nlet myCertPath = \"/opt/myApp/config/myCertificate.pem\"\nlet myKeyPath = \"/opt/myApp/config/myKeyFile.pem\"\n\nlet myConfig = SSLService.Configuration(withCACertificateDirectory: nil, usingCertificateFile: myCertPath, withKeyFile: myKeyFile)\n\n// Create the socket...\nvar socket = try Socket.create()\nguard let socket = socket else {\n  fatalError(\"Could not create socket.\")\n}\n\n// Create and attach the SSLService to the socket...\n//  - Note: if you're going to be using the same \n//          configuration over and over, it'd be \n//          better to create it in the beginning \n//          as `let` constant.\nsocket.delegate = try SSLService(usingConfiguration: myConfig)\n\n// Start listening...\ntry socket.listen(on: 1337)\n\n```\nThe example above creates a `SSL server` socket. Replacing the `socket.listen` function with a `socket.connect` would result in an `SSL client` being created as illustrated below:\n```\n// Connect to the server...\ntry socket.connect(to: \"someplace.org\", port: 1337)\n```\n`SSLService` handles all the negotiation and setup for the secure transfer of data. The determining factor for whether or not a `Socket` is setup as a server or client `Socket` is API which is used to initiate a connection. `listen()` will cause the `Socket` to be setup as a server socket.  Calling `connect()` results a client setup.\n\n### Extending Connection Verification\n\n`SSLService` provides a callback mechanism should you need to specify **additional** verification logic. After creating the instance of `SSLService`, you can set the instance variable `verifyCallback`.  This instance variable has the following signature:\n```\npublic var verifyCallback: ((_ service: SSLService) -\u003e (Bool, String?))? = nil\n```\nSetting this callback is not required. It defaults to `nil` unless set.  The first parameter passed to your callback is the instance of `SSLService` that has this callback.  This will allow you to access the public members of the `SSLService` instance in order to do additional verification.  Upon completion, your callback should return a tuple.  The first value is a `Bool` indicating the sucess or failure of the routine.  The second value is an `optional String` value used to provide a description in the case where verification failed. In the event of callback failure, an `exception` will be thrown by the internal verification function.  **Important Note:** To effectively use this callback requires knowledge of the platforms underlying secure transport service, `Apple Secure Transport` on `supported Apple platforms` and `OpenSSL` on `Linux`.\n\n### Skipping Connection Verification\n\nIf desired, `SSLService` can *skip* the connection verification.  To accomplish this, set the property `skipVerification` to `true` after creating the `SSLService` instance.  However, if the `verifyCallback` property (described above) is set, that callback will be called regardless of this setting. The default for property is false.  It is **NOT** recommended that you skip the connection verification in a `production` environment unless you are providing verification via the `verificationCallback`.\n\n## Community\n\nWe love to talk server-side Swift and Kitura. Join our [Slack](http://swift-at-ibm-slack.mybluemix.net/) to meet the team!\n\n## License\n\nThis library is licensed under Apache 2.0. Full license text is available in [LICENSE](https://github.com/Kitura/BlueSSLService/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKitura%2FBlueSSLService","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKitura%2FBlueSSLService","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKitura%2FBlueSSLService/lists"}