Skip to content

Latest commit

 

History

History
95 lines (68 loc) · 4.57 KB

tls.md

File metadata and controls

95 lines (68 loc) · 4.57 KB
Raw

Using TLS

gRPC Swift offers two TLS 'backends'. A 'NIOSSL' backend and a 'Network.framework' backend.

The NIOSSL backend is available on Darwin and Linux and delegates to SwiftNIO SSL. The Network.framework backend is available on recent Darwin platforms (macOS 10.14+, iOS 12+, tvOS 12+, and watchOS 6+) and uses the TLS implementation provided by Network.framework. Moreover, the Network.framework backend is only compatible with clients and servers using the EventLoopGroup provided by SwiftNIO Transport Services, NIOTSEventLoopGroup.

NIOSSL backend Network.framework backend
Platform Availability Darwin and Linux macOS 10.14+, iOS 12+, tvOS 12+, watchOS 6+
Compatible EventLoopGroup MultiThreadedEventLoopGroup, NIOTSEventLoopGroup NIOTSEventLoopGroup

Note that on supported Darwin platforms users should the prefer using NIOTSEventLoopGroup and the Network.framework backend.

Configuring TLS

TLS may be configured in two different ways: using a client/server builder, or by constructing a configuration object to instantiate the builder with.

Configuring a Client

The simplest way to configure a client to use TLS is to let gRPC decide which TLS backend to use based on the type of the provided EventLoopGroup:

let group = PlatformSupport.makeEventLoopGroup(loopCount: 1)
let builder = ClientConnection.usingPlatformAppropriateTLS(for: group)

The builder exposes additional methods for configuring TLS, however most methods are specific to a backend and must not be called when that backend is not being used (the documentation for each withTLS(...) method states which backend it may be applied to).

If more control is required over the configuration users may signal which backend to use and provide an appropriate EventLoopGroup to one of ClientConnection.usingTLSBackedByNIOSSL(on:) and ClientConnection.usingTLSBackedByNetworkFramework(on:).

gRPC Swift also includes a GRPCTLSConfiguration object which wraps the configuration used by each backend. An instance of this may also be provided to ClientConnection.usingTLS(with:on:) with an appropriate EventLoopGroup.

Configuring a Server

Servers always require some backend specific configuration, as such there is no automatically detectable 'platform appropriate' server configuration.

To configure a server callers must pair one of Server.usingTLSBackedByNIOSSL(on:certificateChain:privateKey:) and Server.usingTLSBackedByNetworkFramework(on:with:) with an appropriate EventLoopGroup or provide a GRPCTLSConfiguration and appropriate EventLoopGroup to Server.usingTLS(with:on:).

NIOSSL Backend: Loading Certificates and Private Keys

Using the NIOSSL backend, certificates and private keys are represented by NIOSSLCertificate and NIOSSLPrivateKey, respectively.

A certificate or private key may be loaded from:

  • a file using NIOSSLCertificate(file:format:) or NIOSSLPrivateKey(file:format:), or
  • an array of bytes using NIOSSLCertificate(buffer:format:) or NIOSSLPrivateKey(bytes:format).

It is also possible to load a certificate or private key from a String by constructing an array from its UTF8 view and passing it to the appropriate initializer (NIOSSLCertificate(buffer:format) or NIOSSLPrivateKey(bytes:format:)):

let certificateString = ...
let bytes: = Array(certificateString.utf8)

let certificateFormat = ...
let certificate = try NIOSSLCertificate(buffer: bytes, format: certificateFormat)

Certificate chains may also be loaded from:

  • a file: NIOSSLCertificate.fromPEMFile(_:), or
  • an array of bytes: NIOSSLCertificate.fromPEMBytes(_:).

These functions return an array of certificates ([NIOSSLCertificate]).

Similar to loading a certificate, a certificate chain may also be loaded from a String using by using the UTF8 view on the string with the fromPEMBytes(_:) method.

Refer to the certificate or private key documentation for more information.