ACCUMULO-3476 Initial user manual entries for SSL
Project: http://git-wip-us.apache.org/repos/asf/accumulo/repo Commit: http://git-wip-us.apache.org/repos/asf/accumulo/commit/dc585068 Tree: http://git-wip-us.apache.org/repos/asf/accumulo/tree/dc585068 Diff: http://git-wip-us.apache.org/repos/asf/accumulo/diff/dc585068 Branch: refs/heads/master Commit: dc585068b7f5249423540b1c8203817be7a5e12d Parents: 410e6a2 Author: Josh Elser <els...@apache.org> Authored: Tue Jan 13 18:09:28 2015 -0500 Committer: Josh Elser <els...@apache.org> Committed: Tue Jan 13 18:19:22 2015 -0500 ---------------------------------------------------------------------- .../accumulo_user_manual.tex | 1 + .../latex/accumulo_user_manual/chapters/ssl.tex | 141 +++++++++++++++++++ 2 files changed, 142 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/accumulo/blob/dc585068/docs/src/main/latex/accumulo_user_manual/accumulo_user_manual.tex ---------------------------------------------------------------------- diff --git a/docs/src/main/latex/accumulo_user_manual/accumulo_user_manual.tex b/docs/src/main/latex/accumulo_user_manual/accumulo_user_manual.tex index be26a48..4eacf5c 100644 --- a/docs/src/main/latex/accumulo_user_manual/accumulo_user_manual.tex +++ b/docs/src/main/latex/accumulo_user_manual/accumulo_user_manual.tex @@ -48,6 +48,7 @@ Version 1.6} \include{chapters/analytics} \include{chapters/security} \include{chapters/implementation} +\include{chapters/ssl} \include{chapters/administration} \include{chapters/multivolume} \include{chapters/troubleshooting} http://git-wip-us.apache.org/repos/asf/accumulo/blob/dc585068/docs/src/main/latex/accumulo_user_manual/chapters/ssl.tex ---------------------------------------------------------------------- diff --git a/docs/src/main/latex/accumulo_user_manual/chapters/ssl.tex b/docs/src/main/latex/accumulo_user_manual/chapters/ssl.tex new file mode 100644 index 0000000..0ddf7e2 --- /dev/null +++ b/docs/src/main/latex/accumulo_user_manual/chapters/ssl.tex @@ -0,0 +1,141 @@ + +% Licensed to the Apache Software Foundation (ASF) under one or more +% contributor license agreements. See the NOTICE file distributed with +% this work for additional information regarding copyright ownership. +% The ASF licenses this file to You under the Apache License, Version 2.0 +% (the "License"); you may not use this file except in compliance with +% the License. You may obtain a copy of the License at +% +% http://www.apache.org/licenses/LICENSE-2.0 +% +% Unless required by applicable law or agreed to in writing, software +% distributed under the License is distributed on an "AS IS" BASIS, +% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +% See the License for the specific language governing permissions and +% limitations under the License. + +\chapter{SSL} +Accumulo, through Thrift's TSSLTransport, provides the ability to encrypt +wire communication between Accumulo servers and clients using secure +sockets layer (SSL). SSL certifcates signed by the same certificate authority +control the "circle of trust" in which a secure connection can be established. +Typically, each host running Accumulo processes would be given a certificate +which identifies itself. + +Clients can optionally also be given a certificate, when client-auth is enabled, +which prevents unwanted clients from accessing the system. The SSL integration +presently provides no authentication support within Accumulo (an Accumulo username +and password are still required) and is only used to establish a means for +secure communication. + +\section{Server configuration} + +As previously mentioned, the circle of trust is established by the certificate +authority which created the certificates in use. Because of the tight coupling +of certificate generation with an organization's policies, Accumulo does not +provide a method in which to automatically create the necessary SSL components. + +Administrators without existing infrastructure built on SSL are encourage to +use OpenSSL and the \texttt{keytool} command. An example of these commands are +included in a section below. Accumulo servers require a certificate and keystore, +in the form of Java KeyStores, to enable SSL. The following configuration assumes +these files already exist. + +In \texttt{\$ACCUMULO\_CONF\_DIR/accumulo-site.xml}, the following properties are required: + +\begin{enumerate} +\item{\texttt{rpc.javax.net.ssl.keyStore=The path on the local filesystem to the keystore containing the server's certificate}} +\item{\texttt{rpc.javax.net.ssl.keyStorePassword=The password for the keystore containing the server's certificate}} +\item{\texttt{rpc.javax.net.ssl.trustStore=The path on the local filesystem to the keystore containing the certificate authority's public key}} +\item{\texttt{rpc.javax.net.ssl.trustStorePassword=The password for the keystore containing the certificate authority's public key}} +\item{\texttt{instance.rpc.ssl.enabled=true}} +\end{enumerate} + +Optionally, SSL client-authentication (two-way SSL) can also be enabled by setting +\texttt{instance.rpc.ssl.clientAuth=true} in \texttt{\$ACCUMULO\_CONF\_DIR/accumulo-site.xml}. +This requires that each client has access to valid certificate to set up a secure connection +to the servers. By default, Accumulo uses one-way SSL which does not require clients to have +their own certificate. + +\section{Client configuration} + +To establish a connection to Accumulo servers, each client must also have +special configuration. This is typically accomplished through the use of +the client configuration file whose default location is \texttt{\~/.accumulo/config}. + +The following properties must be set to connect to an Accumulo instance using SSL: + +\begin{enumerate} +\item{\texttt{rpc.javax.net.ssl.trustStore=The path on the local filesystem to the keystore containing the certificate authority's public key}} +\item{\texttt{rpc.javax.net.ssl.trustStorePassword=The password for the keystore containing the certificate authority's public key}} +\item{\texttt{instance.rpc.ssl.enabled=true}} +\end{enumerate} + +If two-way SSL if enabled (\texttt{instance.rpc.ssl.clientAuth=true}) for the instance, the client must also define +their own certificate and enable client authenticate as well. + +\begin{enumerate} +\item{\texttt{rpc.javax.net.ssl.keyStore=The path on the local filesystem to the keystore containing the server's certificate}} +\item{\texttt{rpc.javax.net.ssl.keyStorePassword=The password for the keystore containing the server's certificate}} +\item{\texttt{instance.rpc.ssl.clientAuth=true}} +\end{enumerate} + +\section{Generating SSL material using OpenSSL} + +The following is included as an example for generating your own SSL material (certificate authority and server/client +certificates) using OpenSSL and Java's KeyTool command. + +\subsection{Generate a certificate authority} + +\begin{verbatim} +# Create a private key +openssl genrsa -des3 -out root.key 4096 + +# Create a certificate request using the private key +openssl req -x509 -new -key root.key -days 365 -out root.pem + +# Generate a Base64-encoded version of the PEM just created +openssl x509 -outform der -in root.pem -out root.der + +# Import the key into a Java KeyStore +keytool -import -alias root-key -keystore truststore.jks -file root.der + +# Remove the DER formatted key file (as we don't need it anymore) +rm root.der +\end{verbatim} + +The \texttt{truststore.jks} file is the Java keystore which contains the certificate authority's public key. + +\subsection{Generate a certificate/keystore per host} + +It's common that each host in the instance is issued its own certificate (notably to ensure that revocation procedures +can be easily followed). The following steps can be taken for each host. + +\begin{verbatim} +# Create the private key for our server +openssl genrsa -out server.key 4096 + +# Generate a certificate signing request (CSR) with our private key +openssl req -new -key server.key -out server.csr + +# Use the CSR and the CA to create a certificate for the server (a reply to the CSR) +openssl x509 -req -in server.csr -CA root.pem -CAkey root.key -CAcreateserial \ + -out server.crt -days 365 + +# Use the certificate and the private key for our server to create PKCS12 file +openssl pkcs12 -export -in server.crt -inkey server.key -certfile server.crt \ + -name 'server-key' -out server.p12 + +# Create a Java KeyStore for the server using the PKCS12 file (private key) +keytool -importkeystore -srckeystore server.p12 -srcstoretype pkcs12 -destkeystore \ + server.jks -deststoretype JKS + +# Remove the PKCS12 file as we don't need it +rm server.p12 + +# Import the CA-signed certificate to the keystore +keytool -import -trustcacerts -alias server-crt -file server.crt -keystore server.jks +\end{verbatim} + +The \texttt{server.jks} file is the Java keystore containing the certificate for a given host. The above +methods are equivalent whether the certficate is generate for an Accumulo server or a client.
