Author: lmccay
Date: Sun Mar 22 20:07:57 2015
New Revision: 1668471
URL: http://svn.apache.org/r1668471
Log:
added documentation for using CA signed certificate in Knox
Modified:
knox/site/books/knox-0-5-0/knox-0-5-0.html
knox/site/books/knox-0-6-0/user-guide.html
knox/trunk/books/0.5.0/config.md
knox/trunk/books/0.6.0/config.md
Modified: knox/site/books/knox-0-5-0/knox-0-5-0.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/knox-0-5-0.html?rev=1668471&r1=1668470&r2=1668471&view=diff
==============================================================================
--- knox/site/books/knox-0-5-0/knox-0-5-0.html (original)
+++ knox/site/books/knox-0-5-0/knox-0-5-0.html Sun Mar 22 20:07:57 2015
@@ -462,7 +462,38 @@ ip-10-39-107-209.ec2.internal
</code></pre><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 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. Alternatively, you can set it to another passphrase - take
note of it and set the gateway-identity-passphrase alias to that passphrase
using the Knox CLI.</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="Cre
dential+Store"></a>Credential Store</h5><p>Whenever you provide your own
keystore with either a self-signed cert or an issued certificate signed by a
trusted authority, you will need to set an alias for the
gateway-identity-passphrase or create an empty credential store. This is
necessary for the current release in order for the system to determine the
correct 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
needed. The simplest approach is to create the gateway-identity-passpharse
alias with the Knox CLI. This will create the credential store if it
doesn’t already exist and add the key passphrase.</p><p>See the Knox CLI
section for descriptions of the comman
d 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}/data/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. Alternatively, you can set it to another passphrase - take
note of it and set the gateway-identity-passphrase alias to that passphrase
using the Knox CLI.</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="Usi
ng+a+CA+Signed+Key+Pair"></a>Using a CA Signed Key Pair</h5><p>For certain
deployments a certificate key pair that is signed by a trusted certificate
authority is required. There are a number of different ways in which these
certificates are acquired and can be converted and imported into the Apache
Knox keystore.</p><p>The following steps have been used to do this and are
provided here for guidance in your installation. You may have to adjust
according to your environment.</p><p>General steps:</p>
+<ol>
+ <li>stop gateway and back up all files in
/var/lib/knox/data/security/keystores<br/>gateway.sh stop</li>
+ <li>create new master key for knox and persist, the master key will be
referred to in following steps as $master-key<br/>knoxcli.sh create-master
-force</li>
+ <li>create identity keystore gateway.jks. cert in alias gateway-identity
+ <ul>
+ <li>cd /var/lib/knox/data/security/keystore</li>
+ <li>keytool -genkeypair -alias gateway-identity -keyalg RSA -keysize 1024
-dname “CN=$fqdn_knox,OU=hdp,O=sdge” -keypass $keypass -keystore
gateway.jks -storepass $master-key -validity 300<br/>NOTE: above $fqdn_knox is
the hostname of the knox host. adjust validity as needed. some may choose
$keypass to be the same as $master-key</li>
+ </ul></li>
+ <li>create credential store to store the $keypass in step 3. this creates
__gateway-credentials.jceks file<br/>
+ <ul>
+ <li>knoxcli.sh create-alias gateway-identity-passphrase –value
$keypass</li>
+ </ul></li>
+ <li>generate a certificate signing request from the gateway.jks
+ <ul>
+ <li>keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -certreq -file knox.csr</li>
+ </ul></li>
+ <li>send the knox.csr file to the CA authority and get back the singed
certificate, signed cert referred to as knox.signed in following steps. Also
need the CA cert, which normally can be requested through openssl command or
web browser. (or can ask the CA authority to send a copy).</li>
+ <li>import both the CA authority certificate (referred as corporateCA.cer)
and the signed knox certificate back into gateway.jks
+ <ul>
+ <li>keytool -keystore gateway.jks -storepass $master-key -alias $hwhq
-import -file corporateCA.cer</li>
+ <li>keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -import -file knox.signed<br/>Note: use any alias appropriate
for the corporate CA.</li>
+ </ul></li>
+ <li>restart gateway. check gateway.log to see that gateway started properly
and clusters are deployed. Can check the timestamp on cluster deployment files
+ <ul>
+ <li>ls -alrt /var/lib/knox/data/deployment</li>
+ </ul></li>
+ <li>verify that clients can use the CA authority cert to access Knox (which
is the goal of using public signed cert)
+ <ul>
+ <li>curl –cacert supwin12ad.cer -u hdptester:hadoop -X GET ‘<a
href="https://$fqdn_knox:8443/gateway/$topologyname/webhdfs/v1/tmp?op=LISTSTATUS";>https://$fqdn_knox:8443/gateway/$topologyname/webhdfs/v1/tmp?op=LISTSTATUS</a>’
or can verify through client browser which already has the corporate CA cert
installed.</li>
+ </ul></li>
+</ol><h5><a id="Credential+Store"></a>Credential Store</h5><p>Whenever you
provide your own keystore with either a self-signed cert or an issued
certificate signed by a trusted authority, you will need to set an alias for
the gateway-identity-passphrase or create an empty credential store. This is
necessary for the current release in order for the system to determine the
correct 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
needed. The simplest approach is to create the gateway-identity-passpharse
alias with the Knox CLI. This will create the credential store if it
doesn’t already exist and add the key passphrase.</p><p>See the Knox CLI
section for descrip
tions 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}/data/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>
<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: knox/site/books/knox-0-6-0/user-guide.html
URL:
http://svn.apache.org/viewvc/knox/site/books/knox-0-6-0/user-guide.html?rev=1668471&r1=1668470&r2=1668471&view=diff
==============================================================================
--- knox/site/books/knox-0-6-0/user-guide.html (original)
+++ knox/site/books/knox-0-6-0/user-guide.html Sun Mar 22 20:07:57 2015
@@ -462,7 +462,38 @@ ip-10-39-107-209.ec2.internal
</code></pre><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 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. Alternatively, you can set it to another passphrase - take
note of it and set the gateway-identity-passphrase alias to that passphrase
using the Knox CLI.</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="Cre
dential+Store"></a>Credential Store</h5><p>Whenever you provide your own
keystore with either a self-signed cert or an issued certificate signed by a
trusted authority, you will need to set an alias for the
gateway-identity-passphrase or create an empty credential store. This is
necessary for the current release in order for the system to determine the
correct 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
needed. The simplest approach is to create the gateway-identity-passpharse
alias with the Knox CLI. This will create the credential store if it
doesn’t already exist and add the key passphrase.</p><p>See the Knox CLI
section for descriptions of the comman
d 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}/data/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. Alternatively, you can set it to another passphrase - take
note of it and set the gateway-identity-passphrase alias to that passphrase
using the Knox CLI.</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="U
sing+a+CA+Signed+Key+Pair"></a>Using a CA Signed Key Pair</h5><p>For certain
deployments a certificate key pair that is signed by a trusted certificate
authority is required. There are a number of different ways in which these
certificates are acquired and can be converted and imported into the Apache
Knox keystore.</p><p>The following steps have been used to do this and are
provided here for guidance in your installation. You may have to adjust
according to your environment.</p><p>General steps:</p>
+<ol>
+ <li>stop gateway and back up all files in
/var/lib/knox/data/security/keystores<br/>gateway.sh stop</li>
+ <li>create new master key for knox and persist, the master key will be
referred to in following steps as $master-key<br/>knoxcli.sh create-master
-force</li>
+ <li>create identity keystore gateway.jks. cert in alias gateway-identity
+ <ul>
+ <li>cd /var/lib/knox/data/security/keystore</li>
+ <li>keytool -genkeypair -alias gateway-identity -keyalg RSA -keysize 1024
-dname “CN=$fqdn_knox,OU=hdp,O=sdge” -keypass $keypass -keystore
gateway.jks -storepass $master-key -validity 300<br/>NOTE: above $fqdn_knox is
the hostname of the knox host. adjust validity as needed. some may choose
$keypass to be the same as $master-key</li>
+ </ul></li>
+ <li>create credential store to store the $keypass in step 3. this creates
__gateway-credentials.jceks file<br/>
+ <ul>
+ <li>knoxcli.sh create-alias gateway-identity-passphrase –value
$keypass</li>
+ </ul></li>
+ <li>generate a certificate signing request from the gateway.jks
+ <ul>
+ <li>keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -certreq -file knox.csr</li>
+ </ul></li>
+ <li>send the knox.csr file to the CA authority and get back the singed
certificate, signed cert referred to as knox.signed in following steps. Also
need the CA cert, which normally can be requested through openssl command or
web browser. (or can ask the CA authority to send a copy).</li>
+ <li>import both the CA authority certificate (referred as corporateCA.cer)
and the signed knox certificate back into gateway.jks
+ <ul>
+ <li>keytool -keystore gateway.jks -storepass $master-key -alias $hwhq
-import -file corporateCA.cer</li>
+ <li>keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -import -file knox.signed<br/>Note: use any alias appropriate
for the corporate CA.</li>
+ </ul></li>
+ <li>restart gateway. check gateway.log to see that gateway started properly
and clusters are deployed. Can check the timestamp on cluster deployment files
+ <ul>
+ <li>ls -alrt /var/lib/knox/data/deployment</li>
+ </ul></li>
+ <li>verify that clients can use the CA authority cert to access Knox (which
is the goal of using public signed cert)
+ <ul>
+ <li>curl –cacert supwin12ad.cer -u hdptester:hadoop -X GET ‘<a
href="https://$fqdn_knox:8443/gateway/$topologyname/webhdfs/v1/tmp?op=LISTSTATUS";>https://$fqdn_knox:8443/gateway/$topologyname/webhdfs/v1/tmp?op=LISTSTATUS</a>’
or can verify through client browser which already has the corporate CA cert
installed.</li>
+ </ul></li>
+</ol><h5><a id="Credential+Store"></a>Credential Store</h5><p>Whenever you
provide your own keystore with either a self-signed cert or an issued
certificate signed by a trusted authority, you will need to set an alias for
the gateway-identity-passphrase or create an empty credential store. This is
necessary for the current release in order for the system to determine the
correct 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
needed. The simplest approach is to create the gateway-identity-passpharse
alias with the Knox CLI. This will create the credential store if it
doesn’t already exist and add the key passphrase.</p><p>See the Knox CLI
section for descrip
tions 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}/data/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>
<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: knox/trunk/books/0.5.0/config.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/config.md?rev=1668471&r1=1668470&r2=1668471&view=diff
==============================================================================
--- knox/trunk/books/0.5.0/config.md (original)
+++ knox/trunk/books/0.5.0/config.md Sun Mar 22 20:07:57 2015
@@ -336,6 +336,37 @@ Keytool will prompt you for a number of
See the Knox CLI section for descriptions of the command line utilties related
to the management of the keystores.
+##### Using a CA Signed Key Pair #####
+For certain deployments a certificate key pair that is signed by a trusted
certificate authority is required. There are a number of different ways in
which these certificates are acquired and can be converted and imported into
the Apache Knox keystore.
+
+The following steps have been used to do this and are provided here for
guidance in your installation.
+You may have to adjust according to your environment.
+
+General steps:
+
+1. stop gateway and back up all files in /var/lib/knox/data/security/keystores
+gateway.sh stop
+2. create new master key for knox and persist, the master key will be referred
to in following steps as $master-key
+knoxcli.sh create-master -force
+3. create identity keystore gateway.jks. cert in alias gateway-identity
+ * cd /var/lib/knox/data/security/keystore
+ * keytool -genkeypair -alias gateway-identity -keyalg RSA -keysize 1024
-dname "CN=$fqdn_knox,OU=hdp,O=sdge" -keypass $keypass -keystore gateway.jks
-storepass $master-key -validity 300
+NOTE: above $fqdn_knox is the hostname of the knox host. adjust validity as
needed. some may choose $keypass to be the same as $master-key
+4. create credential store to store the $keypass in step 3. this creates
__gateway-credentials.jceks file
+ * knoxcli.sh create-alias gateway-identity-passphrase --value $keypass
+5. generate a certificate signing request from the gateway.jks
+ * keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -certreq -file knox.csr
+4. send the knox.csr file to the CA authority and get back the singed
certificate, signed cert referred to as knox.signed in following steps. Also
need the CA cert, which normally can be requested through openssl command or
web browser. (or can ask the CA authority to send a copy).
+5. import both the CA authority certificate (referred as corporateCA.cer) and
the signed knox certificate back into gateway.jks
+ * keytool -keystore gateway.jks -storepass $master-key -alias $hwhq
-import -file corporateCA.cer
+ * keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -import -file knox.signed
+Note: use any alias appropriate for the corporate CA.
+6. restart gateway. check gateway.log to see that gateway started properly and
clusters are deployed. Can check the timestamp on cluster deployment files
+ * ls -alrt /var/lib/knox/data/deployment
+7. verify that clients can use the CA authority cert to access Knox (which is
the goal of using public signed cert)
+ * curl --cacert supwin12ad.cer -u hdptester:hadoop -X GET
'https://$fqdn_knox:8443/gateway/$topologyname/webhdfs/v1/tmp?op=LISTSTATUS'
+or can verify through client browser which already has the corporate CA cert
installed.
+
##### Credential Store #####
Whenever you provide your own keystore with either a self-signed cert or an
issued certificate signed by a trusted authority, you will need to set an alias
for the gateway-identity-passphrase or create an empty credential store. This
is necessary for the current release in order for the system to determine the
correct password for the keystore and the key.
Modified: knox/trunk/books/0.6.0/config.md
URL:
http://svn.apache.org/viewvc/knox/trunk/books/0.6.0/config.md?rev=1668471&r1=1668470&r2=1668471&view=diff
==============================================================================
--- knox/trunk/books/0.6.0/config.md (original)
+++ knox/trunk/books/0.6.0/config.md Sun Mar 22 20:07:57 2015
@@ -332,10 +332,41 @@ Keytool will prompt you for a number of
*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. Alternatively, you can set it
to another passphrase - take note of it and set the gateway-identity-passphrase
alias to that passphrase using the Knox CLI.
+*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. Alternatively, you can set it
to another passphrase - take note of it and set the gateway-identity-passphrase
alias to that passphrase using the Knox CLI.
See the Knox CLI section for descriptions of the command line utilties related
to the management of the keystores.
+##### Using a CA Signed Key Pair #####
+For certain deployments a certificate key pair that is signed by a trusted
certificate authority is required. There are a number of different ways in
which these certificates are acquired and can be converted and imported into
the Apache Knox keystore.
+
+The following steps have been used to do this and are provided here for
guidance in your installation.
+You may have to adjust according to your environment.
+
+General steps:
+
+1. stop gateway and back up all files in /var/lib/knox/data/security/keystores
+gateway.sh stop
+2. create new master key for knox and persist, the master key will be referred
to in following steps as $master-key
+knoxcli.sh create-master -force
+3. create identity keystore gateway.jks. cert in alias gateway-identity
+ * cd /var/lib/knox/data/security/keystore
+ * keytool -genkeypair -alias gateway-identity -keyalg RSA -keysize 1024
-dname "CN=$fqdn_knox,OU=hdp,O=sdge" -keypass $keypass -keystore gateway.jks
-storepass $master-key -validity 300
+NOTE: above $fqdn_knox is the hostname of the knox host. adjust validity as
needed. some may choose $keypass to be the same as $master-key
+4. create credential store to store the $keypass in step 3. this creates
__gateway-credentials.jceks file
+ * knoxcli.sh create-alias gateway-identity-passphrase --value $keypass
+5. generate a certificate signing request from the gateway.jks
+ * keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -certreq -file knox.csr
+4. send the knox.csr file to the CA authority and get back the singed
certificate, signed cert referred to as knox.signed in following steps. Also
need the CA cert, which normally can be requested through openssl command or
web browser. (or can ask the CA authority to send a copy).
+5. import both the CA authority certificate (referred as corporateCA.cer) and
the signed knox certificate back into gateway.jks
+ * keytool -keystore gateway.jks -storepass $master-key -alias $hwhq
-import -file corporateCA.cer
+ * keytool -keystore gateway.jks -storepass $master-key -alias
gateway-identity -import -file knox.signed
+Note: use any alias appropriate for the corporate CA.
+6. restart gateway. check gateway.log to see that gateway started properly and
clusters are deployed. Can check the timestamp on cluster deployment files
+ * ls -alrt /var/lib/knox/data/deployment
+7. verify that clients can use the CA authority cert to access Knox (which is
the goal of using public signed cert)
+ * curl --cacert supwin12ad.cer -u hdptester:hadoop -X GET
'https://$fqdn_knox:8443/gateway/$topologyname/webhdfs/v1/tmp?op=LISTSTATUS'
+or can verify through client browser which already has the corporate CA cert
installed.
+
##### Credential Store #####
Whenever you provide your own keystore with either a self-signed cert or an
issued certificate signed by a trusted authority, you will need to set an alias
for the gateway-identity-passphrase or create an empty credential store. This
is necessary for the current release in order for the system to determine the
correct password for the keystore and the key.
