1 files changed, 131 insertions, 0 deletions
diff --git a/qpid/cpp/SSL b/qpid/cpp/SSL
new file mode 100644
index 0000000000..b810d4ef10
--- /dev/null
+++ b/qpid/cpp/SSL
@@ -0,0 +1,131 @@
+                 Using SSL
+                 =========
+
+The implementation and use of SSL has some differences on Linux and
+on Windows.
+
+Linux
+=====
+
+SSL support for Qpid-C++, based on Mozilla's Network Security Services
+library, is provided as two loadable modules: one for the client
+(sslconnector.so), one for the broker (ssl.so). Either these libraries
+should be present in the relevant module directory or the
+'load-module' option (or QPID_LOAD_MODULE environment variable) is
+used to ensure they are loaded.
+
+Broker side SSL Settings (note you can get these by qpidd --help
+providing the ssl.so module is loaded):
+
+SSL Settings:
+  --ssl-use-export-policy              Use NSS export policy
+  --ssl-cert-password-file PATH        File containing password to use for accessing
+                                       certificate database
+  --ssl-cert-db PATH                   Path to directory containing certificate
+                                       database
+  --ssl-cert-name NAME (hostname)      Name of the certificate to use
+  --ssl-port PORT (5671)               Port on which to listen for SSL connections
+  --ssl-require-client-authentication  Forces clients to authenticate in order 
+                                       to establish an SSL connection
+  --ssl-sasl-no-dict                   Disables SASL mechanisms that are vulner able to
+                                       passive dictionary-based password attacks
+
+The first four of these are also available as client options (where
+they must either be in the client config file or set as environment
+variables e.g. QPID_SSL_CERT_DB).
+
+To run either the broker or client you need ssl-cert-db-path to point
+to the directory where relevant certificate and key databases can be
+found.
+
+Certificate databases are set up using certutil (included in the
+nss-tools package on fedora). See the NSS site for examples[1] and
+full details[2].
+
+For a simple testing you can set up a single db with a single self
+signed certificate. E.g (with myhost and mydomain replaced by the
+hostname and domainname of the machine in question respectively):
+
+    mkdir test_cert_db
+    certutil -N -d test_cert_db -f cert.password
+    certutil -S -d test_cert_db -n "myhost.mydomain" \
+             -s "CN=myhost.mydomain" -t "CT,," -x \
+             -f cert.password -z /usr/bin/certutil
+
+Here cert.password is a file with a password in it that will be needed
+for accessing the created db.
+
+The daemon can then be started with something like the following:
+
+./src/qpidd --auth no --load-module src/.libs/ssl.so \
+            --ssl-cert-db ./test_cert_db \
+            --ssl-cert-password-file ./cert.password \
+            --ssl-cert-name myhost.mydomain
+
+then for client set:
+
+QPID_LOAD_MODULE=./src/.libs/sslconnector.so
+QPID_SSL_CERT_DB=./test_cert_db
+
+and run e.g.
+
+./src/tests/perftest --count 10000 -P ssl --port 5671 \
+                     --broker myhost.mydomain
+
+When authentication is enabled, the EXTERNAL mechanism will be
+available on client authenticated SSL connections. This allows the
+clients authorisation id to be taken from the validated client
+certificate (it will be the CN with any DCs present appended as the
+domain, e.g. CN=bob,DC=acme,DC=com would result in an identity of
+bob@acme.com).
+
+[1] http://www.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd.html
+[2] http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
+
+
+Windows
+=======
+
+SSL support for Qpid-C++ on Windows is implemented using the Microsoft
+Secure Channel (Schannel) package.  Currently, only registry based
+certificates scoped to the local machine are supported, however
+Schannel also supports file based and user scoped certificates, so
+additional support could be added as required.  Client certificate
+authentication is not supported at this time.
+
+For testing purposes, a self signed certificate can be created as
+follows (requiring Administrator privilege on more recent versions of
+Windows):
+
+  makecert -ss qpidstore -n "CN=myhost.mydomain" -r -sr localmachine myhost.cer
+
+where "qpidstore" is an abitrary certificate store name.  The
+resulting output file "myhost.cer" is the public key of the
+certificate that will be required by any client that wishes to
+authenticate myhost.
+
+To run the server (also as Administrator on recent Windows versions):
+
+  qpidd --ssl-cert-name myhost.mydomain --ssl-cert-store qpidstore [other-args]
+
+On the Windows client side, the SSL support is available without
+loading a separate support module.  For each machine or separate user
+that will be using qpid, you must import the self signed certificate
+as a trusted root.  This can be done from the MMC certificate snapin
+or directly using certmgr.exe.  From the main window:
+
+  select "Third-Party Root Certification Authorities"
+  select "Action" -> "Import..."
+  then direct the Certificate Import Wizard to the "myhost.cer" file
+
+To test the setup:
+
+  perftest --count 10000 -P ssl --port 5671 --broker myhost.mydomain
+
+To export the certificate to non Windows clients, note that
+"myhost.cer" is the X.509 representation of the public key of the
+certificate in DER format.  Import the certificate into the other
+clients if they support the DER format.  Otherwise the certificate can
+be converted to PEM format using OpenSSL
+
+  openssl x509 -in myhost.cer -inform DER -out myhost.pem -outform PEM