Author: hiranya Date: Mon Jul 6 22:52:28 2009 New Revision: 40903 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=40903
Log: Reviewed and updated the secure vault guide. Modified: branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml Modified: branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml URL: http://wso2.org/svn/browse/wso2/branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml?rev=40903&r1=40902&r2=40903&view=diff ============================================================================== --- branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml (original) +++ branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml Mon Jul 6 22:52:28 2009 @@ -23,60 +23,65 @@ <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> <head> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/> - <title>Securing Secret Information </title> + <title>Securing Confidential Information </title> <link href="css/esb-docs.css" rel="stylesheet" /> <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all" /> </head> <body> -<h1>Securing Secret Information</h1> +<h1>Securing Confidential Information</h1> -<p>This guide describes how secret information keeps as secrets.Secret -Information can be any but currently only uses for securing passwords.</p> +<p> + This guide describes how confidential information can be handled in a + secured manner in the ESB environment. From the context of the ESB + confidential information refers mainly to passwords. But confidential + information could be anything and hence instructions given in this guide + applies to all such confidential information elements. +</p> <h2>Secret Providers</h2> -<p>The word 'secret' was used to refer anything need to keep as -secret. Even current usage is only for passwords, API is for any things. Secret +<p>The word 'secret' is used to refer to anything which needs to be kept as a +secret. Eventhough the current usage is limited to passwords, API supports any type of data. Secret retrieving is done through 'SecretCallbackHandler' implementations. -Currently there are few and can add as needed.</p> +Currently there are a few implementations and more implementations can be added as needed.</p> <ul> <li><strong>JBossEncryptionSecretCallbackHandler</strong></li> </ul> -<p>This is the default way use within the JBoss Application Server to secure -database passwords. Use a hardcode pass phrase (Need to use same pass phrase -that have used for encryption). Admin can encrypt passwords using a pass phrase +<p>This is the default implementation used within the JBoss Application Server to secure +database passwords. It uses a hardcoded pass phrase (Need to use same pass phrase +that have been used for encryption). Admin can encrypt passwords using a pass phrase and hard code that in the 'JBossEncryptionSecretCallbackHandler' -and make close source.</p> +and make the source code closed.</p> <ul> <li><strong>JlineSecretCallbackHandler</strong></li> </ul> -<p>This is a command line approach. Jline provides the way of reading password +<p>This is a command line based approach. Jline provides a way of reading passwords without echoing text - similar to jdk 6 scanners.</p> <ul> <li><strong>JMXSecretCallbackHandler</strong></li> </ul> -<p>This is only support in synapse. Need to use a JMX Console to provide +<p>This is only supported in Synapse. With this we must use a JMX Console to provide secrets. This may be useful for any users that manage servers in a production environment using JMX.</p> <ul> <li><strong>HardCodedSecretCallbackHandler</strong></li> </ul> -<p>Admin needed to hard code password and make close source. This can be used +<p>Admin needs to hard code password and make source code closed. This can be used to just provide keystore passwords and other secrets can be retrieved using -'SecretManagerSecretCallbackHandler' (next one)</p> +'SecretManagerSecretCallbackHandler' (described next)</p> <ul> <li><strong>SecretManagerSecretCallbackHandler</strong></li> </ul> -<p>All secrets are managed using Secret Manager. Secret Manager keeps any -number of secret repositories. Those are arranged in a cascade manner. All -secrets are in one place - secret repositories. Secrets can be accessed by -providing alias for those (no need to put encrypted value in inline in +<p>All secrets are managed using the Secret Manager. Secret Manager can keep +any number of secret repositories. Those are arranged in a cascading manner. All +secrets are stored in one place - secret repositories. Secrets can be accessed by +providing aliases for them (no need to put encrypted value in inline in application configurations). Key Stores needed for Secret Manager and secret repositories are configurable. It can be done through the 'secret-conf.properties'. Currently, there is only one secret @@ -136,7 +141,7 @@ <p></p> <p>For security operations (encrypt / decrypt), Secret Manager uses a KeyStore -and securing the keystore passwords can be done by any of above ways - 4 ways. +and securing the keystore passwords can be done by any of above mentioned ways. In the current implementation, there is only a one Secret Repository - A file based Secret Repository. It is possible to implements secret repositories based on database, directory servers, registry etc.</p> @@ -145,7 +150,7 @@ <h2>General API for Retrieving Secrets</h2> -<p>Consider that an application has configuration for password as</p> +<p>Consider that an application has a configuration for passwords as</p> <pre> <datasource> <password>pass</password> @@ -180,10 +185,10 @@ String actualPassword= secretCallback.getSecret();</pre> -<p>If you want to load multiple secret at one time you can used +<p>If you want to load multiple secrets at once you can use 'MultiSecretCallback'; or array of SingleSecretCallback s.</p> -<p>There is a simple way to avoid code repeating.</p> +<p>There is a simple way to avoid code duplication.</p> <pre>SecretInformation secretInformation = SecretInformationFactory.createSecretInformation(secretProvider, aliasPassword, passwordPrompt); @@ -191,17 +196,18 @@ <h2>Adapting in OSGI Environment</h2> -<p>All 'SecretCallbackHandlers' other than +<p>All 'SecretCallbackHandlers' other than the 'SecretManagerSecretCallbackHandler' are stateless enabling to use -without any extra code. With 'SecretManagerSecretCallbackHandler', -it is better to be there only a one 'SecretManager' instance. More +without any additional code. With 'SecretManagerSecretCallbackHandler', +it is better if there is only one 'SecretManager' instance. More precisely, a single 'SecretManagerSecretCallbackHandler' instance. -For this, there is a carbon module 'secretvault'. It just read -'secret-conf.properties' and initiate a new -'SecretCallbackHandler' instance. This can be +For this, there is a carbon module called 'secretvault'. It just reads +'secret-conf.properties' and initiates a new +'SecretCallbackHandler' instance. This can be a 'SecretManagerSecretCallbackHandler' or any other -'SecretCallbackHandlers' that need to be shared a one instance -globally.To acccess this and use need to following instuctions</p> +'SecretCallbackHandlers' instance that needs to be shared +globally.To acccess this instance one must follow the instuctions +given below.</p> <p></p> @@ -242,16 +248,16 @@ <p><strong>Logic on Set </strong></p> -<p>If the secret that need to be resolved can be accessed directly. For example -passing as an argument. You can use following logic.</p> +<p>If the secret that needs to be resolved can be accessed directlym, for example +passing as an argument, you can use the following logic.</p> <pre> SecretCallbackHandler secretProvider = secretCallbackHandlerService.getSecretCallbackHandler()); SecretInformation secretInformation = SecretInformationFactory.createSecretInformation(secretProvider, aliasPassword, passwordPrompt); String actualPassword = secretInformation.getResolvedSecret();</pre> -<p>Now you can pass either actualPassword or secretProvider or -secretInformation to the code location that uses pasword . But if the code that -do secret resolution can not be accessed. For example, when use a configuration +<p>Now you can pass either an actualPassword or secretProvider or +secretInformation to the code location that uses pasword. But if the code that +performs secret resolution can not be accessed. For example, when using a configuration such as follows - you cannot pass resolved password directly.</p> <pre> <datasource> @@ -269,29 +275,29 @@ as <strong>org.apache.synapse.commons.security.secret.handler.SharedSecretCallbackHandler</strong>. This is another <strong>SecretCallbackHandler</strong> that uses the handler -set out in the <strong>SharedSecretCallbackHandlerCache</strong>. You need to -use <strong>Retrieving API</strong> What do here are use OSGI services in order -to share across any component and use singleton to share across classes in a -single component and enable to use <strong>Retrieving API</strong> as it is.</p> +set in the <strong>SharedSecretCallbackHandlerCache</strong>. You need to +use <strong>Retrieving API</strong>. What we do here is using OSGI services in order +to share across any component and use the Singleton pattern to share across classes in a +single component and enable using the <strong>Retrieving API</strong> as it is.</p> <h2>Ciphertool </h2> -<p>This is a simple tool to encrypt and decrypts simple texts.There are scripts -named ciphertool.sh & ciphertool.bat to achieve this task. The arguments -that are inputs to this tool with their meanings are shown bellow. </p> +<p>This is a simple tool to encrypt and decrypt simple texts.There are scripts +named ciphertool.sh & ciphertool.bat available in the bin directory to launch the tool. The arguments +accepted by this tool with their meanings are shown bellow. </p> <ul> - <li>keystore - If keys are in a store , it's location </li> - <li>storepass - Password for access keyStore </li> + <li>keystore - If keys are in a store , its location </li> + <li>storepass - Password to access keyStore </li> <li>keypass - To get private key </li> <li>alias - Alias to identify key owner </li> - <li>storetype - Type of keyStore , Default is JKS </li> + <li>storetype - Type of keyStore, Default is JKS </li> <li>keyfile - If key is in a file </li> <li>opmode - encrypt or decrypt , Default is encrypt </li> <li>algorithm - encrypt or decrypt algorithm , Default is RSA </li> <li>source - Either cipher or plain text as an in-lined form </li> - <li>outencode - Currently base64 and use for encode result</li> - <li>inencode - Currently base64 and use to decode input </li> - <li>trusted - Is KeyStore a trusted store? If presents this, consider as a + <li>outencode - Currently base64 and used for encoding the result</li> + <li>inencode - Currently base64 and used to decode input </li> + <li>trusted - Is KeyStore a trusted store? If this argument is provided, consider as a trusted store </li> <li>passphrase - if a simple symmetric encryption using a pass phrase shall be used </li> _______________________________________________ Esb-java-dev mailing list [email protected] https://wso2.org/cgi-bin/mailman/listinfo/esb-java-dev
