summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMichael Grunder <michael.grunder@gmail.com>2019-10-10 14:54:01 -0700
committerGitHub <noreply@github.com>2019-10-10 14:54:01 -0700
commit42a2e679bebf3712a2d4403b58fc583dc90357e1 (patch)
treef7de0d14d1b4b8c574ed736acf1b1b0578f1c657
parent18eeeed0769bc669e3d9bb87e887157e7298da92 (diff)
parentc5726ba5f79d255921615bbbfe921b525a313186 (diff)
Merge pull request #720 from yossigo/ssl-docs
Update README with SSL support.
-rw-r--r--README.md62
1 files changed, 60 insertions, 2 deletions
diff --git a/README.md b/README.md
index c0b432f..d48a7e3 100644
--- a/README.md
+++ b/README.md
@@ -404,9 +404,67 @@ This should be done only in order to maximize performances when working with
large payloads. The context should be set back to `REDIS_READER_MAX_BUF` again
as soon as possible in order to prevent allocation of useless memory.
+## SSL/TLS Support
+
+### Building
+
+SSL/TLS support is not built by default and requires an explicit flag:
+
+ make USE_TLS=1
+
+This requires OpenSSL development package (e.g. including header files to be
+available.
+
+When enabled, SSL/TLS support is built into extra `libhiredis_ssl.a` and
+`libhiredis_ssl.so` static/dynamic libraries. This leaves the original libraries
+unaffected so no additional dependencies are introduced.
+
+### Using it
+
+First, you'll need to make sure you include the SSL header file:
+
+```c
+#include "hiredis.h"
+#include "hiredis_ssl.h"
+```
+
+SSL can only be enabled on a `redisContext` connection after the connection has
+been established and before any command has been processed. For example:
+
+```c
+c = redisConnect('localhost', 6443);
+if (c == NULL || c->err) {
+ /* Handle error and abort... */
+}
+
+if (redisSecureConnection(c,
+ "cacertbundle.crt", /* File name of trusted CA/ca bundle file */
+ "client_cert.pem", /* File name of client certificate file */
+ "client_key.pem", /* File name of client privat ekey */
+ "redis.mydomain.com" /* Server name to request (SNI) */
+ ) != REDIS_OK) {
+ printf("SSL error: %s\n", c->errstr);
+ /* Abort... */
+}
+```
+
+You will also need to link against `libhiredis_ssl`, **in addition** to
+`libhiredis` and add `-lssl -lcrypto` to satisfy its dependencies.
+
+### OpenSSL Global State Initialization
+
+OpenSSL needs to have certain global state initialized before it can be used.
+Using `redisSecureConnection()` will handle this automatically on the first
+call.
+
+**If the calling application itself also initializes and uses OpenSSL directly,
+`redisSecureConnection()` must not be used.**
+
+Instead, use `redisInitiateSSL()` which also provides greater control over the
+configuration of the SSL connection, as the caller is responsible to create a
+connection context using `SSL_new()` and configure it as required.
+
## AUTHORS
Hiredis was written by Salvatore Sanfilippo (antirez at gmail) and
Pieter Noordhuis (pcnoordhuis at gmail) and is released under the BSD license.
-Hiredis is currently maintained by Matt Stancliff (matt at genges dot com) and
-Jan-Erik Rediger (janerik at fnordig dot com)