From d2318c0a286daf51b4fe8afc5c6a232eee71ca72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 25 Nov 2013 15:02:42 +0100
Subject: Add a manual

This is the manual for what is going to be in 1.0. It includes
two things that are not in the code yet: the shutdown option
and the accept_ack transport callback.
---
 manual/ranch_ssl.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 manual/ranch_ssl.md

(limited to 'manual/ranch_ssl.md')

diff --git a/manual/ranch_ssl.md b/manual/ranch_ssl.md
new file mode 100644
index 0000000..d8bb140
--- /dev/null
+++ b/manual/ranch_ssl.md
@@ -0,0 +1,97 @@
+ranch_ssl
+=========
+
+The `ranch_ssl` module implements an SSL Ranch transport.
+
+Types
+-----
+
+### opts() = [{backlog, non_neg_integer()}
+	| {cacertfile, string()}
+	| {cacerts, [Der::binary()]}
+	| {cert, Der::binary()}
+	| {certfile, string()}
+	| {ciphers, [ssl:erl_cipher_suite()] | string()}
+	| {fail_if_no_peer_cert, boolean()}
+	| {hibernate_after, integer() | undefined}
+	| {ip, inet:ip_address()}
+	| {key, Der::binary()}
+	| {keyfile, string()}
+	| {next_protocols_advertised, [binary()]}
+	| {nodelay, boolean()}
+	| {password, string()}
+	| {port, inet:port_number()}
+	| {raw, non_neg_integer(), non_neg_integer(), non_neg_integer() | binary()}
+	| {reuse_session, fun()}
+	| {reuse_sessions, boolean()}
+	| {secure_renegotiate, boolean()}
+	| {verify, ssl:verify_type()}
+	| {verify_fun, {fun(), InitialUserState::term()}}]
+
+> Listen options.
+>
+> This does not represent the entirety of the options that can
+> be set on the socket, but only the options that should be
+> set independently of protocol implementation.
+
+Option descriptions
+-------------------
+
+Specifying a certificate is mandatory, either through the `cert`
+or the `certfile` option. None of the other options are required.
+
+The default value is given next to the option name.
+
+ -  backlog (1024)
+   -  Max length of the queue of pending connections.
+ -  cacertfile
+   -  Path to PEM encoded trusted certificates file used to verify peer certificates.
+ -  cacerts
+   -  List of DER encoded trusted certificates.
+ -  cert
+   -  DER encoded user certificate.
+ -  certfile
+   -  Path to the PEM encoded user certificate file. May also contain the private key.
+ -  ciphers
+   -  List of ciphers that clients are allowed to use.
+ -  fail_if_no_peer_cert (false)
+   -  Whether to refuse the connection if the client sends an empty certificate.
+ -  hibernate_after (undefined)
+   -  Time in ms after which SSL socket processes go into hibernation to reduce memory usage.
+ -  ip
+   -  Interface to listen on. Listen on all interfaces by default.
+ -  key
+   -  DER encoded user private key.
+ -  keyfile
+   -  Path to the PEM encoded private key file, if different than the certfile.
+ -  next_protocols_advertised
+   -  List of protocols to send to the client if it supports the Next Protocol extension.
+ -  nodelay (true)
+   -  Whether to enable TCP_NODELAY.
+ -  password
+   -  Password to the private key file, if password protected.
+ -  port (0)
+   -  TCP port number to listen on. 0 means a random port will be used.
+ -  reuse_session
+   -  Custom policy to decide whether a session should be reused.
+ -  reuse_sessions (false)
+   -  Whether to allow session reuse.
+ -  secure_renegotiate (false)
+   -  Whether to reject renegotiation attempts that do not conform to RFC5746.
+ -  verify (verify_none)
+   -  Use `verify_peer` to request a certificate from the client.
+ -  verify_fun
+   -  Custom policy to decide whether a client certificate is valid.
+
+Note that the client will not send a certificate unless the
+value for the `verify` option is set to `verify_peer`. This
+means that the `fail_if_no_peer_cert` only apply when combined
+with the `verify` option. The `verify_fun` option allows
+greater control over the client certificate validation.
+
+The `raw` option is unsupported.
+
+Exports
+-------
+
+None.
-- 
cgit v1.2.3