SQOOP-2876: Sqoop2: Document TLS support

(Abraham Fine via Jarek Jarcec Cecho)

docs/src/site/sphinx/security/AuthenticationAndAuthorization.rst

@@ -14,9 +14,9 @@
    limitations under the License.
 
 
-=========================
-Security Guide On Sqoop 2
-=========================
+================================
+Authentication and Authorization
+================================
 
 Most Hadoop components, such as HDFS, Yarn, Hive, etc., have security frameworks, which support Simple, Kerberos and LDAP authentication. currently Sqoop 2 provides 2 types of authentication: simple and kerberos. The authentication module is pluggable, so more authentication types can be added. Additionally, a new role based access control is introduced in Sqoop 1.99.6. We recommend to use this capability in multi tenant environments, so that malicious users can’t easily abuse your created link and job objects.
 

docs/src/site/sphinx/security/Encryption.rst

@@ -0,0 +1,102 @@
+.. 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.
+
+
+==========
+Encryption
+==========
+
+Sqoop 2 offers an HTTP REST-like API as the mechanism by which clients can
+communicate with the Sqoop 2 server. The Sqoop 2 server and the Sqoop 2 shell
+have support for TLS/SSL.
+
+Keystore Generation
+===================
+
+Sqoop 2 uses the JKS format. Details on how to create JKS files can be found here:
+`Generating a KeyStore and TrustStore <https://docs.oracle.com/cd/E19509-01/820-3503/6nf1il6er/index.html>`_
+
+Server Configuration
+=====================
+
+All Sqoop 2 server TLS/SSL configuration occurs in the Sqoop configuration file,
+normally in ``<Sqoop Folder>/conf/sqoop.properties``.
+
+First, TLS must be enabled:
+
+::
+
+   org.apache.sqoop.security.tls.enabled=true
+
+A protocol should be specified. Please find a list of options here:
+`Standard Algorithm Name Documentation <http://docs.oracle.com/javase/7/docs/technotes/guides/security/StandardNames.html#SSLContext>`_
+
+::
+
+   org.apache.sqoop.security.tls.protocol="TLSv1.2"
+
+
+Configure the path to the JKS keystore:
+
+::
+
+   org.apache.sqoop.security.tls.keystore=/Users/abe/mykeystore.jks
+
+Configure the keystore password and the key manager password:
+
+::
+
+   org.apache.sqoop.security.tls.keystore_password=keystorepassword
+   org.apache.sqoop.security.tls.keymanager_password=keymanagerpassword
+
+Alternatively, the password can be specified using generators.
+
+Generators are commands that the Sqoop propess will execute, and then retrieve the
+password from standard out. The generator will only be run if no standard password
+is configured.
+
+::
+
+   org.apache.sqoop.security.tls.keystore_password_generator=echo keystorepassword
+   org.apache.sqoop.security.tls.keymanager_password=echo keymanagerpassword
+
+Client/Shell Configuration
+--------------------------
+
+When using TLS on the Sqoop 2 server, especially with a self-signed certificate,
+it may be useful to specify a truststore for the client/shell to use.
+
+The truststore for the shell is configured via a command. In practice, it may be
+useful to put this command inside the system sqoop rc file (``/etc/sqoop2/conf/sqoop2rc``)
+or the user's rc file (``~/.sqoop2rc``).
+
+::
+
+   sqoop:000> set truststore --truststore /Users/abefine/keystore/node2.truststore
+   Truststore set successfully
+
+You may also include a password. Passwords are not required for truststores.
+
+::
+
+   sqoop:000> set truststore --truststore /Users/abefine/keystore/node2.truststore --truststore-password changeme
+   Truststore set successfully
+
+You may also use a password generator.
+
+::
+
+   sqoop:000> set truststore --truststore /Users/abefine/keystore/node2.truststore --truststore-password-generator "echo changeme"
+   Truststore set successfully