From c5f8aa41eeafbb23f73956c00ff575c933073fbc Mon Sep 17 00:00:00 2001
From: Ryan Culpepper <ryanc@racket-lang.org>
Date: Sat, 17 Nov 2012 16:34:12 -0500
Subject: [PATCH] add some basic notes on using ssl securely

---
 collects/openssl/openssl.scrbl | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/collects/openssl/openssl.scrbl b/collects/openssl/openssl.scrbl
index d30ac742de..7c795a9953 100644
--- a/collects/openssl/openssl.scrbl
+++ b/collects/openssl/openssl.scrbl
@@ -42,6 +42,35 @@ value is @racket[#f] (library not loaded) will raise an exception.}
 Either @racket[#f] (when @racket[ssl-available?] is @racket[#t]) or an
 error string (when @racket[ssl-available?] is @racket[#f]).}
 
+@; ----------------------------------------------------------------------
+
+@section{Using SSL Securely}
+
+SSL and TLS are client-server cryptographic protocols that enable
+secure communication with remote hosts (called ``peers''). But SSL
+must be properly configured in order to be secure.
+
+The security of client programs using SSL generally depends
+on the authentication of the server credentials, which requires proper
+initialization of this library's client contexts. To use SSL securely,
+a client program must at a minimum take the following steps:
+
+@itemlist[
+
+@item{create an SSL client context using @racket[ssl-make-client-context]}
+
+@item{tell the context what certificate authorities to trust using
+@racket[ssl-load-verify-root-certificates!]}
+
+@item{turn on certificate verification using @racket[ssl-set-verify!]
+(or check each connection individually using @racket[ssl-peer-verified?])}
+
+@item{turn on hostname verification using
+@racket[ssl-set-verify-hostname!] (or check each connection
+individually using @racket[ssl-peer-check-hostname])}
+]
+
+
 @; ----------------------------------------------------------------------
 
 @section{TCP-like Client Procedures}