From daa6ca8b5e23276e1da2d81ae2f2ac7dc8b69b0d Mon Sep 17 00:00:00 2001
From: Jan Steemann <jan@arangodb.com>
Date: Thu, 26 Jul 2012 13:39:21 +0200
Subject: [PATCH] added documentation for ssl options

---
 Doxygen/Examples.ArangoDB/openssl-ciphers     |  8 ++
 Doxygen/Examples.ArangoDB/openssl-options     |  9 ++
 Doxygen/Examples.ArangoDB/server-keyfile      | 10 +++
 .../Examples.ArangoDB/server-keyfile-openssl  | 17 ++++
 .../Documentation/command-line-options.dox    | 26 +++++-
 arangod/RestServer/ArangoServer.h             |  2 +-
 lib/HttpsServer/ApplicationHttpsServer.h      | 87 ++++++++++++++++++-
 7 files changed, 155 insertions(+), 4 deletions(-)
 create mode 100644 Doxygen/Examples.ArangoDB/openssl-ciphers
 create mode 100644 Doxygen/Examples.ArangoDB/openssl-options
 create mode 100644 Doxygen/Examples.ArangoDB/server-keyfile
 create mode 100644 Doxygen/Examples.ArangoDB/server-keyfile-openssl

diff --git a/Doxygen/Examples.ArangoDB/openssl-ciphers b/Doxygen/Examples.ArangoDB/openssl-ciphers
new file mode 100644
index 0000000000..068db8041f
--- /dev/null
+++ b/Doxygen/Examples.ArangoDB/openssl-ciphers
@@ -0,0 +1,8 @@
+> openssl ciphers -v
+
+ECDHE-RSA-AES256-SHA    SSLv3 Kx=ECDH     Au=RSA  Enc=AES(256)  Mac=SHA1
+ECDHE-ECDSA-AES256-SHA  SSLv3 Kx=ECDH     Au=ECDSA Enc=AES(256)  Mac=SHA1
+DHE-RSA-AES256-SHA      SSLv3 Kx=DH       Au=RSA  Enc=AES(256)  Mac=SHA1
+DHE-DSS-AES256-SHA      SSLv3 Kx=DH       Au=DSS  Enc=AES(256)  Mac=SHA1
+DHE-RSA-CAMELLIA256-SHA SSLv3 Kx=DH       Au=RSA  Enc=Camellia(256) Mac=SHA1
+...
diff --git a/Doxygen/Examples.ArangoDB/openssl-options b/Doxygen/Examples.ArangoDB/openssl-options
new file mode 100644
index 0000000000..532b8af543
--- /dev/null
+++ b/Doxygen/Examples.ArangoDB/openssl-options
@@ -0,0 +1,9 @@
+> grep "#define SSL_OP_.*" /usr/include/openssl/ssl.h
+
+#define SSL_OP_MICROSOFT_SESS_ID_BUG                    0x00000001L
+#define SSL_OP_NETSCAPE_CHALLENGE_BUG                   0x00000002L
+#define SSL_OP_LEGACY_SERVER_CONNECT                    0x00000004L
+#define SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG         0x00000008L
+#define SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG              0x00000010L
+#define SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER               0x00000020L
+...
diff --git a/Doxygen/Examples.ArangoDB/server-keyfile b/Doxygen/Examples.ArangoDB/server-keyfile
new file mode 100644
index 0000000000..46539d0a7a
--- /dev/null
+++ b/Doxygen/Examples.ArangoDB/server-keyfile
@@ -0,0 +1,10 @@
+-----BEGIN CERTIFICATE-----
+
+(base64 encoded certificate)
+
+-----END CERTIFICATE-----
+-----BEGIN RSA PRIVATE KEY-----
+
+(base64 encoded private key)
+
+-----END RSA PRIVATE KEY-----
diff --git a/Doxygen/Examples.ArangoDB/server-keyfile-openssl b/Doxygen/Examples.ArangoDB/server-keyfile-openssl
new file mode 100644
index 0000000000..c85a30f4ca
--- /dev/null
+++ b/Doxygen/Examples.ArangoDB/server-keyfile-openssl
@@ -0,0 +1,17 @@
+# create private key in file "server.key"
+openssl genrsa -des3 -out server.key 1024
+
+# create certificate signing request (csr) in file "server.csr"
+openssl req -new -key server.key -out server.csr
+
+# copy away original private key to "server.key.org"
+cp server.key server.key.org
+
+# remove passphrase from the private key
+openssl rsa -in server.key.org -out server.key
+
+# sign the csr with the key, creates certificate file "server.crt"
+openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
+
+# combine certificate and key into single file "ssl.keyfile"
+cat server.crt server.key > ssl.keyfile
diff --git a/arangod/Documentation/command-line-options.dox b/arangod/Documentation/command-line-options.dox
index 7b29f42ccd..8b18e71c91 100644
--- a/arangod/Documentation/command-line-options.dox
+++ b/arangod/Documentation/command-line-options.dox
@@ -47,6 +47,12 @@
 ///     <ul>
 ///      <li>@ref CommandLineArangoEndpoint "server.endpoint"</li>
 ///      <li>@ref CommandLineArangoDisableAuthentication "server.disable-authentication"</li>
+///      <li>@ref CommandLineArangoKeyFile "server.keyfile"</li>
+///      <li>@ref CommandLineArangoCaFile "server.cafile"</li>
+///      <li>@ref CommandLineArangoSslProtocol "server.ssl-protocol</li>
+///      <li>@ref CommandLineArangoSslCacheMode "server.ssl-cache-mode</li>
+///      <li>@ref CommandLineArangoSslOptions "server.ssl-options</li>
+///      <li>@ref CommandLineArangoSslCipherList "server.ssl-cipher-list</li>
 ///      <li>@ref CommandLineArangoDirectory "database.directory"</li>
 ///      <li>@ref CommandLineArangoMaximalJournalSize "database.maximal-journal-size"</li>
 ///      <li>@ref CommandLineArangoWaitForSync "database.wait-for-sync"</li>
@@ -163,8 +169,26 @@
 /// @anchor CommandLineArangoDisableAuthentication
 /// @copydetails triagens::arango::ArangoServer::_disableAuthentication
 ///
+/// @anchor CommandLineArangoKeyFile
+/// @copydetails triagens::rest::ApplicationHttpsServer::_httpsKeyfile
+///
+/// @anchor CommandLineArangoCaFile
+/// @copydetails triagens::rest::ApplicationHttpsServer::_cafile
+///
+/// @anchor CommandLineArangoSslProtocol
+/// @copydetails triagens::rest::ApplicationHttpsServer::_sslProtocol
+///
+/// @anchor CommandLineArangoSslCacheMode
+/// @copydetails triagens::rest::ApplicationHttpsServer::_sslCacheMode
+///
+/// @anchor CommandLineArangoSslOptions
+/// @copydetails triagens::rest::ApplicationHttpsServer::_sslOptions
+///
+/// @anchor CommandLineArangoSslCipherList
+/// @copydetails triagens::rest::ApplicationHttpsServer::_sslCipherList
+///
 /// @anchor CommandLineArangoDisableAdminInterface
-/// @CMDOPT{--disable-admin-interface}
+/// @CMDOPT{--server.disable-admin-interface}
 ///
 /// If this option is specified, then the HTML admininstration interface at 
 /// URL http://server:port/ will be disabled and cannot used by any user at all.
diff --git a/arangod/RestServer/ArangoServer.h b/arangod/RestServer/ArangoServer.h
index 0fd7a11ccb..719e96c919 100644
--- a/arangod/RestServer/ArangoServer.h
+++ b/arangod/RestServer/ArangoServer.h
@@ -326,7 +326,7 @@ namespace triagens {
 ///
 /// @CMDOPT{--server.disable-authentication @CA{value}}
 ///
-/// Settings @CA{value} to true will turn off authentication on the server side
+/// Setting @CA{value} to true will turn off authentication on the server side
 /// so all clients can execute any action without authorisation and privilege
 /// checks.
 ///
diff --git a/lib/HttpsServer/ApplicationHttpsServer.h b/lib/HttpsServer/ApplicationHttpsServer.h
index e21889a3a2..38b2d0dfc3 100644
--- a/lib/HttpsServer/ApplicationHttpsServer.h
+++ b/lib/HttpsServer/ApplicationHttpsServer.h
@@ -233,37 +233,120 @@ namespace triagens {
         vector<HttpsServer*> _httpsServers;
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief keyfile
+/// @brief keyfile containing server certificate
+///
+/// @CMDOPT{--server.keyfile @CA{filename}}
+///
+/// If SSL encryption is used, this option must be used to specify the filename
+/// of the server private key. The file must contain both an X509 certificate and
+/// the server's private key.
+///
+/// The file specified by @CA{filename} should have the following structure:
+///
+/// @verbinclude server-keyfile
+///
+/// You may use certificates issued by a Certificate Authority or self-signed
+/// certificates. Self-signed certificates can be created by a tool of your 
+/// choice. When using OpenSSL for creating the self-signed certificate, the 
+/// following commands should create a keyfile:
+/// 
+/// @verbinclude server-keyfile-openssl
+///
+/// For further information please check the manuals of the tools you use to
+/// create the certificate.
+///
+/// Note: the --server.keyfile option must be set if the server is started with 
+/// at least one SSL endpoint.
 ////////////////////////////////////////////////////////////////////////////////
 
         string _httpsKeyfile;
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief CA file
+///
+/// @CMDOPT{--server.cafile @CA{filename}}
+///
+/// This option can be used to specify the file which contains the CA certificates
+/// of clients.
+///
+/// TODO
+///
+/// Note: this option is only relevant if at least one SSL endpoint is used.
 ////////////////////////////////////////////////////////////////////////////////
 
         string _cafile;
 
 ////////////////////////////////////////////////////////////////////////////////
-/// @brief ssl protocol to use
+/// @brief SSL protocol type to use
+///
+/// @CMDOPT{--server.ssl-protocol @CA{value}}
+///
+/// Use this option to specify the default encryption protocol to be used. 
+/// The following variants are available:
+/// - 1: SSLv2
+/// - 2: SSLv23
+/// - 3: SSLv3
+/// - 4: TLSv1
+///
+/// The default @CA{value} is 4 (i.e. TLSv1).
+///
+/// Note: this option is only relevant if at least one SSL endpoint is used.
 ////////////////////////////////////////////////////////////////////////////////
 
         uint32_t _sslProtocol;
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief ssl cache mode to use
+///
+/// @CMDOPT{--server.ssl-cache-mode @CA{value}}
+///
+/// TODO
+///
+/// Note: this option is only relevant if at least one SSL endpoint is used.
 ////////////////////////////////////////////////////////////////////////////////
 
         uint64_t _sslCacheMode;
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief ssl options to use
+///
+/// @CMDOPT{--server.ssl-options @CA{value}}
+///
+/// This option can be used to set various SSL-related options. Individual 
+/// option values must be combined using bitwise OR.
+///
+/// Which options are available on your platform is determined by the OpenSSL
+/// version you use. The list of options available on your platform might be
+/// retrieved by the following shell command:
+///
+/// @verbinclude openssl-options
+///
+/// A description of the options can be found online in the OpenSSL documentation 
+/// at: http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
+/// 
+/// Note: this option is only relevant if at least one SSL endpoint is used.
 ////////////////////////////////////////////////////////////////////////////////
 
         uint64_t _sslOptions;
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief ssl cipher list to use
+/// 
+/// @CMDOPT{--server.ssl-cipher-list @CA{cipher-list}}
+///
+/// This option can be used to restrict the server to certain SSL ciphers only,
+/// and to define the relative usage preference of SSL ciphers.
+///
+/// The format of @CA{cipher-list} is documented in the OpenSSL documentation.
+///  
+/// To check which ciphers are available on your platform, you may use the 
+/// following shell command:
+/// 
+/// @verbinclude openssl-ciphers
+///
+/// The default value for @CA{cipher-list} is "ALL".
+/// 
+/// Note: this option is only relevant if at least one SSL endpoint is used.
 ////////////////////////////////////////////////////////////////////////////////
 
         string _sslCipherList;