Browse Source

Document how to create certificates/private keys from a string (#699)

Motivation:

It was not clear to some users how to create certificates or private
keys from a string.

See: https://github.com/grpc/grpc-swift/issues/697

Modifications:

Update the tls.md doc to explain how to create certificates and private
keys from strings.

Result:

Better docs.
George Barnett 5 years ago
parent
commit
d32b3ae180
1 changed files with 38 additions and 0 deletions
  1. 38 0
      docs/tls.md

+ 38 - 0
docs/tls.md

@@ -27,4 +27,42 @@ The `TLS` configuration is a subset of [`TLSConfiguration`][nio-ref-tlsconfig]
 provided by `NIOSSL` to ensure it meets the gRPC specification. Users may also
 initialize `TLS` with `TLSConfiguration` should they require.
 
+## Loading Certificates and Private Keys
+
+Certificate and private key objects ([`NIOSSLCertificate`][nio-ref-tlscert] and
+[`NIOSSLPrivateKey`][nio-ref-privatekey]) are provided by SwiftNIO SSL.
+
+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:)`):
+
+```swift
+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]`).
+
+Simillar 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][nio-ref-tlscert] or [private
+key][nio-ref-privatekey] documentation for more information.
+
+[nio-ref-privatekey]: https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/Classes/NIOSSLPrivateKey.html
+[nio-ref-tlscert]: https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/Classes/NIOSSLCertificate.html
 [nio-ref-tlsconfig]: https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/Structs/TLSConfiguration.html