knox-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lmc...@apache.org
Subject svn commit: r1562549 - in /incubator/knox: site/books/knox-incubating-0-4-0/knox-incubating-0-4-0.html site/index.html site/issue-tracking.html site/license.html site/mail-lists.html site/project-info.html site/team-list.html trunk/books/0.4.0/config.md
Date Wed, 29 Jan 2014 19:01:07 GMT
Author: lmccay
Date: Wed Jan 29 19:01:06 2014
New Revision: 1562549

URL: http://svn.apache.org/r1562549
Log:
updates for knoxcli

Modified:
    incubator/knox/site/books/knox-incubating-0-4-0/knox-incubating-0-4-0.html
    incubator/knox/site/index.html
    incubator/knox/site/issue-tracking.html
    incubator/knox/site/license.html
    incubator/knox/site/mail-lists.html
    incubator/knox/site/project-info.html
    incubator/knox/site/team-list.html
    incubator/knox/trunk/books/0.4.0/config.md

Modified: incubator/knox/site/books/knox-incubating-0-4-0/knox-incubating-0-4-0.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/books/knox-incubating-0-4-0/knox-incubating-0-4-0.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/books/knox-incubating-0-4-0/knox-incubating-0-4-0.html (original)
+++ incubator/knox/site/books/knox-incubating-0-4-0/knox-incubating-0-4-0.html Wed Jan 29
19:01:06 2014
@@ -396,7 +396,7 @@ ip-10-39-107-209.ec2.internal
 </topology>
 </code></pre><h5><a id="Hostmap+Provider+Configuration"></a>Hostmap
Provider Configuration</h5><p>Details about each provider configuration element
is enumerated below.</p>
 <dl><dt>topology/gateway/provider/role</dt><dd>The role for a Hostmap
provider must always be <code>hostmap</code>.</dd><dt>topology/gateway/provider/name</dt><dd>The
Hostmap provider supplied out-of-the-box is selected via the name <code>static</code>.</dd><dt>topology/gateway/provider/enabled</dt><dd>Host
mapping can be enabled or disabled by providing <code>true</code> or <code>false</code>.</dd><dt>topology/gateway/provider/param</dt><dd>Host
mapping is configured by providing parameters for each external to internal mapping.</dd><dt>topology/gateway/provider/param/name</dt><dd>The
parameter names represent an external host names associated with the internal host names provided
by the value element. This can be a comma separated list of host names that all represent
the same physical host. When mapping from internal to external host name the first external
host name in the list is used.</dd><dt>topology/gateway/provider/param/value</dt><dd>The
parameter values represent the inte
 rnal host names associated with the external host names provider by the name element. This
can be a comma separated list of host names that all represent the same physical host. When
mapping from external to internal host names the first internal host name in the list is used.</dd>
-</dl><h4><a id="Logging"></a>Logging</h4><p>If necessary
you can enable additional logging by editing the <code>log4j.properties</code>
file in the <code>conf</code> directory. Changing the rootLogger value from <code>ERROR</code>
to <code>DEBUG</code> will generate a large amount of debug logging. A number
of useful, more fine loggers are also provided in the file.</p><h4><a id="Java+VM+Options"></a>Java
VM Options</h4><p>TODO - Java VM options doc.</p><h4><a id="Persisting+the+Master+Secret"></a>Persisting
the Master Secret</h4><p>The master secret is required to start the server. This
secret is used to access secured artifacts by the gateway instance. Keystore, trust stores
and credential stores are all protected with the master secret.</p><p>You may
persist the master secret by supplying the <em>-persist-master</em> switch at
startup. This will result in a warning indicating that persisting the secret is less secure
than providing it at startup. We do make some provisions in ord
 er to protect the persisted password.</p><p>It is encrypted with AES 128 bit
encryption and where possible the file permissions are set to only be accessible by the user
that the gateway is running as.</p><p>After persisting the secret, ensure that
the file at config/security/master has the appropriate permissions set for your environment.
This is probably the most important layer of defense for master secret. Do not assume that
the encryption if sufficient protection.</p><p>A specific user should be created
to run the gateway this will protect a persisted master file.</p><h4><a id="Management+of+Security+Artifacts"></a>Management
of Security Artifacts</h4><p>There are a number of artifacts that are used by
the gateway in ensuring the security of wire level communications, access to protected resources
and the encryption of sensitive data. These artifacts can be managed from outside of the gateway
instances or generated and populated by the gateway instance itself.</p><p>The
followi
 ng is a description of how this is coordinated with both standalone (development, demo, etc)
gateway instances and instances as part of a cluster of gateways in mind.</p><p>Upon
start of the gateway server we:</p>
+</dl><h4><a id="Logging"></a>Logging</h4><p>If necessary
you can enable additional logging by editing the <code>log4j.properties</code>
file in the <code>conf</code> directory. Changing the rootLogger value from <code>ERROR</code>
to <code>DEBUG</code> will generate a large amount of debug logging. A number
of useful, more fine loggers are also provided in the file.</p><h4><a id="Java+VM+Options"></a>Java
VM Options</h4><p>TODO - Java VM options doc.</p><h4><a id="Persisting+the+Master+Secret"></a>Persisting
the Master Secret</h4><p>The master secret is required to start the server. This
secret is used to access secured artifacts by the gateway instance. Keystore, trust stores
and credential stores are all protected with the master secret.</p><p>You may
persist the master secret by supplying the <em>-persist-master</em> switch at
startup. This will result in a warning indicating that persisting the secret is less secure
than providing it at startup. We do make some provisions in ord
 er to protect the persisted password.</p><p>It is encrypted with AES 128 bit
encryption and where possible the file permissions are set to only be accessible by the user
that the gateway is running as.</p><p>After persisting the secret, ensure that
the file at config/security/master has the appropriate permissions set for your environment.
This is probably the most important layer of defense for master secret. Do not assume that
the encryption if sufficient protection.</p><p>A specific user should be created
to run the gateway this user will be the only user with permissions for the persisted master
file.</p><p>See the Knox CLI section for descriptions of the command line utilties
related to the master secret.</p><h4><a id="Management+of+Security+Artifacts"></a>Management
of Security Artifacts</h4><p>There are a number of artifacts that are used by
the gateway in ensuring the security of wire level communications, access to protected resources
and the encryption of sensitive data. T
 hese artifacts can be managed from outside of the gateway instances or generated and populated
by the gateway instance itself.</p><p>The following is a description of how this
is coordinated with both standalone (development, demo, etc) gateway instances and instances
as part of a cluster of gateways in mind.</p><p>Upon start of the gateway server
we:</p>
 <ol>
   <li>Look for an identity store at <code>conf/security/keystores/gateway.jks</code>.
 The identity store contains the certificate and private key used to represent the identity
of the server for SSL connections and signature creation.
   <ul>
@@ -419,7 +419,8 @@ ip-10-39-107-209.ec2.internal
 <ol>
   <li>Using a single gateway instance as a master instance the artifacts can be generated
or placed into the expected location and then replicated across all of the slave instances
before startup.</li>
   <li>Using an NFS mount as a central location for the artifacts would provide a single
source of truth without the need to replicate them over the network. Of course, NFS mounts
have their own challenges.</li>
-</ol><h4><a id="Keystores"></a>Keystores</h4><p>In order
to provide your own certificate for use by the gateway, you will need to either import an
existing key pair into a Java keystore or generate a self-signed cert using the Java keytool.</p><h5><a
id="Importing+a+key+pair+into+a+Java+keystore"></a>Importing a key pair into a Java
keystore</h5><h1><a id="----NEEDS+TESTING"></a>&mdash;-NEEDS TESTING</h1><p>One
way to accomplish this is to start with a PKCS12 store for your key pair and then convert
it to a Java keystore or JKS.</p>
+  <li>Using the KnoxCLI to create and manage the security artifacts.</li>
+</ol><p>See the Knox CLI section for descriptions of the command line utilties
related to the security artifact management.</p><h4><a id="Keystores"></a>Keystores</h4><p>In
order to provide your own certificate for use by the gateway, you will need to either import
an existing key pair into a Java keystore or generate a self-signed cert using the Java keytool.</p><h5><a
id="Importing+a+key+pair+into+a+Java+keystore"></a>Importing a key pair into a Java
keystore</h5><h1><a id="----NEEDS+TESTING"></a>&mdash;-NEEDS TESTING</h1><p>One
way to accomplish this is to start with a PKCS12 store for your key pair and then convert
it to a Java keystore or JKS.</p>
 <pre><code>openssl pkcs12 -export -in cert.pem -inkey key.pem &gt; server.p12
 </code></pre><p>The above example uses openssl to create a PKCS12 encoded
store for your provided certificate private key.</p>
 <pre><code>keytool -importkeystore -srckeystore {server.p12} -destkeystore gateway.jks
-srcstoretype pkcs12
@@ -431,10 +432,7 @@ ip-10-39-107-209.ec2.internal
 </ol><p>NOTE: The password for the keystore as well as that of the imported key
must be the master secret for the gateway instance.</p><h1><a id="----END+NEEDS+TESTING"></a>&mdash;-END
NEEDS TESTING</h1><h5><a id="Generating+a+self-signed+cert+for+use+in+testing+or+development+environments"></a>Generating
a self-signed cert for use in testing or development environments</h5>
 <pre><code>keytool -genkey -keyalg RSA -alias gateway-identity -keystore gateway.jks
\
     -storepass {master-secret} -validity 360 -keysize 2048
-</code></pre><p>Keytool will prompt you for a number of elements used that
will comprise this distiniguished name (DN) within your certificate. </p><p><em>NOTE:</em>
When it prompts you for your First and Last name be sure to type in the hostname of the machine
that your gateway instance will be running on. This is used by clients during hostname verification
to ensure that the presented certificate matches the hostname that was used in the URL for
the connection - so they need to match.</p><p><em>NOTE:</em> When
it prompts for the key password just press enter to ensure that it is the same as the keystore
password. Which as was described earlier must match the master secret for the gateway instance.</p><h5><a
id="Credential+Store"></a>Credential Store</h5><p>Whenever you provide
your own keystore with either a self-signed cert or a real certificate signed by a trusted
authority, you will need to create an empty credential store. This is necessary for the current
release in order fo
 r the system to utilize the same password for the keystore and the key.</p><p>The
credential stores in Knox use the JCEKS keystore type as it allows for the storage of general
secrets in addition to certificates.</p>
-<pre><code>keytool -genkey -alias {anything} -keystore __gateway-credentials.jceks
\
-    -storepass {master-secret} -validity 360 -keysize 1024 -storetype JCEKS
-</code></pre><p>Follow the prompts again for the DN for the cert of the
credential store. This certificate isn&rsquo;t really used for anything at the moment
but is required to create the credential store.</p><h5><a id="Provisioning+of+Keystores"></a>Provisioning
of Keystores</h5><p>Once you have created these keystores you must move them into
place for the gateway to discover them and use them to represent its identity for SSL connections.
This is done by copying the keystores to the <code>{GATEWAY_HOME}/conf/security/keystores</code>
directory for your gateway install.</p><h4><a id="Summary+of+Secrets+to+be+Managed"></a>Summary
of Secrets to be Managed</h4>
+</code></pre><p>Keytool will prompt you for a number of elements used will
comprise the distiniguished name (DN) within your certificate. </p><p><em>NOTE:</em>
When it prompts you for your First and Last name be sure to type in the hostname of the machine
that your gateway instance will be running on. This is used by clients during hostname verification
to ensure that the presented certificate matches the hostname that was used in the URL for
the connection - so they need to match.</p><p><em>NOTE:</em> When
it prompts for the key password just press enter to ensure that it is the same as the keystore
password. Which as was described earlier must match the master secret for the gateway instance.</p><p>See
the Knox CLI section for descriptions of the command line utilties related to the management
of the keystores.</p><h5><a id="Credential+Store"></a>Credential Store</h5><p>Whenever
you provide your own keystore with either a self-signed cert or a real certificate signed
by a trusted 
 authority, you will need to create an empty credential store. This is necessary for the current
release in order for the system to utilize the same password for the keystore and the key.</p><p>The
credential stores in Knox use the JCEKS keystore type as it allows for the storage of general
secrets in addition to certificates.</p><p>Keytool may be used to create credential
stores but the Knox CLI section details how to create aliases. These aliases are managed within
credential stores which are created by the CLI as appropriate. </p><p>See the
Knox CLI section for descriptions of the command line utilties related to the management of
the credential stores.</p><h5><a id="Provisioning+of+Keystores"></a>Provisioning
of Keystores</h5><p>Once you have created these keystores you must move them into
place for the gateway to discover them and use them to represent its identity for SSL connections.
This is done by copying the keystores to the <code>{GATEWAY_HOME}/conf/security/keystores</cod
 e> directory for your gateway install.</p><h4><a id="Summary+of+Secrets+to+be+Managed"></a>Summary
of Secrets to be Managed</h4>
 <ol>
   <li>Master secret - the same for all gateway instances in a cluster of gateways</li>
   <li>All security related artifacts are protected with the master secret</li>

Modified: incubator/knox/site/index.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/index.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/index.html (original)
+++ incubator/knox/site/index.html Wed Jan 29 19:01:06 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 17, 2014 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 29, 2014 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140117" />
+    <meta name="Date-Revision-yyyymmdd" content="20140129" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-01-17</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-01-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: incubator/knox/site/issue-tracking.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/issue-tracking.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/issue-tracking.html (original)
+++ incubator/knox/site/issue-tracking.html Wed Jan 29 19:01:06 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 17, 2014 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 29, 2014 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140117" />
+    <meta name="Date-Revision-yyyymmdd" content="20140129" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-01-17</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-01-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: incubator/knox/site/license.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/license.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/license.html (original)
+++ incubator/knox/site/license.html Wed Jan 29 19:01:06 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 17, 2014 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 29, 2014 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140117" />
+    <meta name="Date-Revision-yyyymmdd" content="20140129" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-01-17</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-01-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: incubator/knox/site/mail-lists.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/mail-lists.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/mail-lists.html (original)
+++ incubator/knox/site/mail-lists.html Wed Jan 29 19:01:06 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 17, 2014 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 29, 2014 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140117" />
+    <meta name="Date-Revision-yyyymmdd" content="20140129" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-01-17</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-01-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: incubator/knox/site/project-info.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/project-info.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/project-info.html (original)
+++ incubator/knox/site/project-info.html Wed Jan 29 19:01:06 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 17, 2014 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 29, 2014 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140117" />
+    <meta name="Date-Revision-yyyymmdd" content="20140129" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-01-17</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-01-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: incubator/knox/site/team-list.html
URL: http://svn.apache.org/viewvc/incubator/knox/site/team-list.html?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/site/team-list.html (original)
+++ incubator/knox/site/team-list.html Wed Jan 29 19:01:06 2014
@@ -1,5 +1,5 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 17, 2014 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 29, 2014 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
@@ -10,7 +10,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20140117" />
+    <meta name="Date-Revision-yyyymmdd" content="20140129" />
     <meta http-equiv="Content-Language" content="en" />
                                                     
 <script type="text/javascript">var _gaq = _gaq || [];
@@ -57,7 +57,7 @@
                         <a href="https://cwiki.apache.org/confluence/display/KNOX/Index"
class="externalLink" title="Wiki">Wiki</a>
               
                     
-                &nbsp;| <span id="publishDate">Last Published: 2014-01-17</span>
+                &nbsp;| <span id="publishDate">Last Published: 2014-01-29</span>
               &nbsp;| <span id="projectVersion">Version: 0.0.0-SNAPSHOT</span>
             </div>
       <div class="clear">

Modified: incubator/knox/trunk/books/0.4.0/config.md
URL: http://svn.apache.org/viewvc/incubator/knox/trunk/books/0.4.0/config.md?rev=1562549&r1=1562548&r2=1562549&view=diff
==============================================================================
--- incubator/knox/trunk/books/0.4.0/config.md (original)
+++ incubator/knox/trunk/books/0.4.0/config.md Wed Jan 29 19:01:06 2014
@@ -251,8 +251,9 @@ After persisting the secret, ensure that
 This is probably the most important layer of defense for master secret.
 Do not assume that the encryption if sufficient protection.
 
-A specific user should be created to run the gateway this will protect a persisted master
file.
+A specific user should be created to run the gateway this user will be the only user with
permissions for the persisted master file.
 
+See the Knox CLI section for descriptions of the command line utilties related to the master
secret.
 
 #### Management of Security Artifacts ####
 
@@ -287,6 +288,9 @@ By leveraging the algorithm described ab
 
 1. Using a single gateway instance as a master instance the artifacts can be generated or
placed into the expected location and then replicated across all of the slave instances before
startup.
 2. Using an NFS mount as a central location for the artifacts would provide a single source
of truth without the need to replicate them over the network. Of course, NFS mounts have their
own challenges.
+3. Using the KnoxCLI to create and manage the security artifacts.
+
+See the Knox CLI section for descriptions of the command line utilties related to the security
artifact management.
 
 #### Keystores ####
 In order to provide your own certificate for use by the gateway, you will need to either
import an existing key pair into a Java keystore or generate a self-signed cert using the
Java keytool.
@@ -318,21 +322,22 @@ NOTE: The password for the keystore as w
     keytool -genkey -keyalg RSA -alias gateway-identity -keystore gateway.jks \
         -storepass {master-secret} -validity 360 -keysize 2048
 
-Keytool will prompt you for a number of elements used that will comprise this distiniguished
name (DN) within your certificate. 
+Keytool will prompt you for a number of elements used will comprise the distiniguished name
(DN) within your certificate. 
 
 *NOTE:* When it prompts you for your First and Last name be sure to type in the hostname
of the machine that your gateway instance will be running on. This is used by clients during
hostname verification to ensure that the presented certificate matches the hostname that was
used in the URL for the connection - so they need to match.
 
 *NOTE:* When it prompts for the key password just press enter to ensure that it is the same
as the keystore password. Which as was described earlier must match the master secret for
the gateway instance.
 
+See the Knox CLI section for descriptions of the command line utilties related to the management
of the keystores.
+
 ##### Credential Store #####
 Whenever you provide your own keystore with either a self-signed cert or a real certificate
signed by a trusted authority, you will need to create an empty credential store. This is
necessary for the current release in order for the system to utilize the same password for
the keystore and the key.
 
 The credential stores in Knox use the JCEKS keystore type as it allows for the storage of
general secrets in addition to certificates.
 
-    keytool -genkey -alias {anything} -keystore __gateway-credentials.jceks \
-        -storepass {master-secret} -validity 360 -keysize 1024 -storetype JCEKS
+Keytool may be used to create credential stores but the Knox CLI section details how to create
aliases. These aliases are managed within credential stores which are created by the CLI as
appropriate. 
 
-Follow the prompts again for the DN for the cert of the credential store. This certificate
isn't really used for anything at the moment but is required to create the credential store.
+See the Knox CLI section for descriptions of the command line utilties related to the management
of the credential stores.
 
 ##### Provisioning of Keystores #####
 Once you have created these keystores you must move them into place for the gateway to discover
them and use them to represent its identity for SSL connections. This is done by copying the
keystores to the `{GATEWAY_HOME}/conf/security/keystores` directory for your gateway install.



Mime
View raw message