You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@slider.apache.org by jm...@apache.org on 2014/07/11 20:41:04 UTC
svn commit: r1609766 - in /incubator/slider/site/trunk/content: ./ design/
docs/ images/
Author: jmaron
Date: Fri Jul 11 18:41:04 2014
New Revision: 1609766
URL: http://svn.apache.org/r1609766
Log:
SLIDER-227 SSL documentation modifications
Added:
incubator/slider/site/trunk/content/design/ssl_implementation.md
incubator/slider/site/trunk/content/docs/ssl.md
incubator/slider/site/trunk/content/images/agent_am_one_way_ssl.png (with props)
incubator/slider/site/trunk/content/images/agent_am_two_way_ssl.png (with props)
incubator/slider/site/trunk/content/images/server_cert_gen.png (with props)
incubator/slider/site/trunk/content/images/server_ssl_startup.png (with props)
Modified:
incubator/slider/site/trunk/content/design/architecture.md
incubator/slider/site/trunk/content/design/index.md
incubator/slider/site/trunk/content/index.md
Modified: incubator/slider/site/trunk/content/design/architecture.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/design/architecture.md?rev=1609766&r1=1609765&r2=1609766&view=diff
==============================================================================
--- incubator/slider/site/trunk/content/design/architecture.md (original)
+++ incubator/slider/site/trunk/content/design/architecture.md Fri Jul 11 18:41:04 2014
@@ -139,4 +139,7 @@ In an insecure Hadoopp cluster, the Slid
To enable access to the database files as that submitting use, the identity of the user is provided when the AM is created; the
AM will pass this same identity down to the created containers. This information *identifies* the user -but does not *authenticate* them: they are trusted to be who they claim to be.
+### Agent to Application Master Secure Communication
+By default, one-way SSL is leveraged to secure the communication between Slider agents and the Application Master. However, two-way SSL can be enabled. A more detailed discussion of the SSL implementation in Slider can be found [here](/design/ssl_implementation.html).
+
Modified: incubator/slider/site/trunk/content/design/index.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/design/index.md?rev=1609766&r1=1609765&r2=1609766&view=diff
==============================================================================
--- incubator/slider/site/trunk/content/design/index.md (original)
+++ incubator/slider/site/trunk/content/design/index.md Fri Jul 11 18:41:04 2014
@@ -21,4 +21,5 @@
* [Application Needs](/docs/slider_specs/application_needs.html)
* [Specification](/design/specification/index.html)
* [Service Registry](/design/registry/index.html)
+* [SSL Implementation](/design/ssl_implementation.html)
* [Role history](/design/rolehistory.html)
Added: incubator/slider/site/trunk/content/design/ssl_implementation.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/design/ssl_implementation.md?rev=1609766&view=auto
==============================================================================
--- incubator/slider/site/trunk/content/design/ssl_implementation.md (added)
+++ incubator/slider/site/trunk/content/design/ssl_implementation.md Fri Jul 11 18:41:04 2014
@@ -0,0 +1,71 @@
+#Agent to Application Master SSL Communication
+Slider agents are configured to communicate with the Slider Application Master using SSL. By default, one-way SSL authentication is enabled (i.e., the agent verifies the identity of the application master). However, two-way SSL authentication can be enabled to further secure the communication channel.
+
+## Application Master SSL Support
+There are two primary components enabling server-side SSL support:
+
+* The server's certificate mananger
+* The agent-facing HTTPS Server
+
+###Server Certificate Manager
+As the Slider application master starts up it leverages the certificate manager to ensure that the resources required to support SSL transport - the server certificate, the key store, and the truststore - are available. The certificate manager will create these artifacts if necessary (see figure 1).
+
+
+
+Figure 1 - Server Certificate and Keystore/Trustore Generation
+
+###Agent HTTPS Server
+Once the artifacts necessary for supporting SSL transport are available, the agent-facing HTTP server instance is created and started. This instance creates two SSL connectors. The first connector is always configured for one-way SSL and supports server liveness checks from the agents, the retrieval of the server certificate, and the creation of signed agent certificates (the latter two tasks are required for the two-way SSL support). The second connector provides the port over which agent registration and heart beats are transmitted. It is configured for one-way SSL by default but can be explicitly configured for two-way SSL (hence the need for a certificate exchange mechanism as detailed above). Figure 2 illustrates this startup sequence.
+
+
+
+Figure 2 - Server Agent-facing HTTP Server Initialization
+
+## Agent Communication Modes
+The agent and application master communicate over HTTPS in one of two modes:
+
+1. One-way SSL
+2. Two-way SSL
+
+### One-way SSL
+This is the default communication mode between the agent and application master. One-way SSL authentication requires the client to verify the identity of the server, but the server does not verify the identify of the client (in this case, the agent).
+
+The sequence of events for the setup of agent to AM one-way SSL communication is:
+
+1. The Agent attempt to connect to the AM's one-way SSL port (see Agent HTTPS server discussion above).
+2. If the agent receives an HTTP OK response (Status 200), it proceeds with sending a registration request to the AM over the secured port (in this case, also configured for one-way SSL).
+3. Once the agent receives the registration response, it proceeds with the sending of heartbeat messages.
+
+See Figure 3 for an illustration of this sequence.
+
+
+
+Figure 3 - Agent to AM One-way SSL Communication
+
+### Two-way SSL
+The setup for two-way SSL is more involves since both parties must have each others certificates available to establish the trust required for this authentication mechanism. Therefore, in between the liveness check and registration performed in the one-way SSL mode, the agent and application master perform some additional steps to setup their certificate stores:
+
+1. The agent downloads the application master's certificate using the one-way SSL port
+2. The agent generates a key
+3. The agent uploads the key and requests a signed certificate from the application master
+4. The application master signs the key, creates a certificate, and returns it in the response to the client. It also store the certificate in its keystore/truststore.
+
+After this exchange of information, the two parties are configured for communication over the configured two-way SSL port. See Figure 4 for an illustration of this exchange.
+
+
+
+Figure 3 - Agent to AM Two-way SSL Communication
+
+Note that two-way SSL is enabled by setting a property ("ssl.server.client.auth") for the slider application master in the application configuration:
+
+```
+ "components": {
+ "slider-appmaster": {
+ "jvm.heapsize": "256M",
+ "ssl.server.client.auth": "true"
+ },
+```
+
+
+
+
\ No newline at end of file
Added: incubator/slider/site/trunk/content/docs/ssl.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/docs/ssl.md?rev=1609766&view=auto
==============================================================================
--- incubator/slider/site/trunk/content/docs/ssl.md (added)
+++ incubator/slider/site/trunk/content/docs/ssl.md Fri Jul 11 18:41:04 2014
@@ -0,0 +1,14 @@
+#Set Up Two-Way SSL Between the Slider Agents and the Application Master
+Two-way SSL provides a higher level of secure communication between the Slider Application Master and Agents by requiring both to verify each other's identify prior to the exchange of HTTP requests and responses. By default the communication mechanism between the two is One-Way SSL. To enable Two-way SSL:
+
+* Edit the application configuration file for the application you intend to deploy
+* Modify the "slider-appmaster" component configuration by adding the "ssl.server.client.auth" property with a value of "true":
+
+```
+ "components": {
+ "slider-appmaster": {
+ "jvm.heapsize": "256M",
+ "ssl.server.client.auth": "true"
+ },
+```
+* Create and start the cluster (e.g. by using the slider command line leveraging the "create" option)
Added: incubator/slider/site/trunk/content/images/agent_am_one_way_ssl.png
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/images/agent_am_one_way_ssl.png?rev=1609766&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/slider/site/trunk/content/images/agent_am_one_way_ssl.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/slider/site/trunk/content/images/agent_am_two_way_ssl.png
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/images/agent_am_two_way_ssl.png?rev=1609766&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/slider/site/trunk/content/images/agent_am_two_way_ssl.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/slider/site/trunk/content/images/server_cert_gen.png
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/images/server_cert_gen.png?rev=1609766&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/slider/site/trunk/content/images/server_cert_gen.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: incubator/slider/site/trunk/content/images/server_ssl_startup.png
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/images/server_ssl_startup.png?rev=1609766&view=auto
==============================================================================
Binary file - no diff available.
Propchange: incubator/slider/site/trunk/content/images/server_ssl_startup.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: incubator/slider/site/trunk/content/index.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/index.md?rev=1609766&r1=1609765&r2=1609766&view=diff
==============================================================================
--- incubator/slider/site/trunk/content/index.md (original)
+++ incubator/slider/site/trunk/content/index.md Fri Jul 11 18:41:04 2014
@@ -70,6 +70,7 @@ code changes and as of this writing, it
* [Client Configuration](/docs/client-configuration.html)
* [Client Exit Codes](/docs/exitcodes.html)
* [Security](/docs/security.html)
+* [Agent to AM SSL](/docs/ssl.html)
* [How to define a new slider-packaged application](/docs/slider_specs/index.html)
* [Application configuration model](/docs/configuration/index.html)
* [Debugging](/docs/debugging.html)
@@ -90,7 +91,8 @@ code changes and as of this writing, it
* [Overview](/design/architecture.html)
* [Application Needs](/docs/slider_specs/application_needs.html)
* [Expected Behavior](/design/specification/index.html)
-* [Service Registry](/design/registry/index.html)
+* [Service Registry](/design/registry/index.html)
+* [SSL Implementation](/design/ssl_implementation.html)
* [Role History](/design/rolehistory.html)