Author: indika Date: Wed Jun 24 22:29:51 2009 New Revision: 39844 URL: http://wso2.org/svn/browse/wso2?view=rev&revision=39844
Log: securing password initial doc Added: branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml Added: 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?pathrev=39844 ============================================================================== --- (empty file) +++ branches/esb/java/2.1/product/docs/xdoc/securing_secret_information.xml Wed Jun 24 22:29:51 2009 @@ -0,0 +1,295 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- +~ Copyright (c) 2009, WSO2 Inc. (http://www.wso2.org) All Rights Reserved. +~ +~ WSO2 Inc. 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. +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml";> +<head> + <meta content="text/html; charset=iso-8859-1" http-equiv="content-type" /> + <title>WSO2 ESB - Extending Synapse </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> + +<p>This guide describes how secret information keeps as secrets.Secret +Information can be any but currently only uses for securing passwords.</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 +retrieving is done through ‘SecretCallbackHandler’ implementations. +Currently there are few and can add 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 +and hard code that in the ‘JBossEncryptionSecretCallbackHandler’ +and make close source.</p> +<ul> + <li><strong>JlineSecretCallbackHandler</strong></li> +</ul> + +<p>This is a command line approach. Jline provides the way of reading password +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 +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 +to just provide keystore passwords and other secrets can be retrieved using +‘SecretManagerSecretCallbackHandler’ (next one)</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 +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 +repository and it is FileBaseSecretRepository. It uses cipher-text.properties +to keep secrets. It keeps aliases vs. its actual secret in encrypted format +(encrypted by a key in keystore)</p> + +<p><strong>Example</strong></p> +<pre>aliases=synapse + +synapse.secret=EsY65tztE9R5b9pErVxLp8Br5d3ol6vRdWAkYHdc7XkZteGf37VJ+iNlCenqxYSEto0vcjpcmmzwf7K2wd9u3KQtVGKEoNLSe2LYZtrm3tKmGd6PX9YpdN72ml3JISNXPJ69yybFi6DVUIJfE5MFOd7gswWfCnkmZ3eJ6M1nuiI= + +synapse.secret.algorithm=RSA</pre> + +<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. +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> + +<p></p> + +<h2>General API for Retrieving Secrets</h2> + +<p>Consider that an application has configuration for password as</p> + +<p></p> +<pre> <datasource> + <password>pass</password> + <secretProvider>any implementation of SecretCallbackHandler- class name</secretProvider> + </datasource> </pre> + +<p></p> + +<p>For JBossEncryptionSecretCallbackHandler , ‘password’ should +contain an encrypted value. In any other case, it is just an alias- can keep +any human readable text. For example in Secret Manger, actual password is in +secret repositories. For file based repository, it is something like bellow.</p> +<pre> + aliases=pass + pass.secret=EsY65tztE9R5b9pErVxLp8Br5d3ol6vRdWAkYHdc7XkZteGf37VJ+iNlCenqxYSEto0vcjpcmmzwf7K2wd9u3KQtVGKEoNLSe2LYZtrm3tKmGd6PX9YpdN72ml3JISNXPJ69yybFi6DVUIJfE5MFOd7gswWfCnkmZ3eJ6M1nuiI=</pre> + +<p></p> + +<p>To retrieve secret, it is needed to use following API and follow steps.</p> + +<p></p> + +<h3>Retrieving API</h3> + +<p>Read the configuration parameter value of ‘secret Provider’ - +say ‘secretProvider’</p> +<pre>// Create SecretCallbackHandler + SecretCallbackHandler secretCallbackHanlder SecretCallbackHandlerFactory.createSecretCallbackHandler(secretProvider); + +// Setup SecretLoadingModule with +CallbackHandlersSecretLoadingModule secretLoadingModule = new SecretLoadingModule(); +secretLoadingModule.init(new SecretCallbackHandler[]{secretCallbackHanlder}); + +// Create SecretCallbacks +SingleSecretCallback secretCallback = new SingleSecretCallback(aliases); // for above example 'aliases' is ‘pass’ + +secretLoadingModule.load(new SecretCallback[]{secretCallback}); + +String actualPassword= secretCallback.getSecret();</pre> + +<p></p> + +<p>If you want to load multiple secret at one time you can used +‘MultiSecretCallback’ or array of SingleSecretCallback s.</p> + +<p>There is a simple way to avoid code repeating.</p> + +<p></p> +<pre>SecretInformation secretInformation = SecretInformationFactory.createSecretInformation(secretProvider, aliasPassword, passwordPrompt); + +String actualPassword = secretInformation.getResolvedSecret();</pre> + +<p></p> + +<h2>Adapting in OSGI Environment</h2> + +<p></p> + +<p>All ‘SecretCallbackHandlers’ other than +‘SecretManagerSecretCallbackHandler’ are stateless enabling to use +without any extra code. With ‘SecretManagerSecretCallbackHandler’, +it is better to be there only a 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 +‘SecretManagerSecretCallbackHandler’ or any other +‘SecretCallbackHandlers’ that need to be shared a one instance +globally.To acccess this and use need to following instuctions</p> + +<p></p> + +<p><strong>Step 1 - Adding Dependencies </strong></p> + +<p></p> +<pre><dependency> + <groupId>org.apache.synapse</groupId> + <artifactId>synapse-commons</artifactId> + <version>1.3.0.wso2v1</version> +</dependency> + +<dependency> + <groupId>org.wso2.carbon</groupId> + <artifactId>org.wso2.carbon.securevault</artifactId> + <version>${carbon.version}</version> +</dependency></pre> + +<p></p> + +<p><strong>Setp 2 - Listening to SecretCallbackHandlerService</strong></p> + +<p></p> + +<p><pre>* @scr.reference name="secret.callback.handler.service" +* interface="org.wso2.carbon.securevault.SecretCallbackHandlerService" +* cardinality="1..1" policy="dynamic" +* bind="setSecretCallbackHandlerService" unbind="unsetSecretCallbackHandlerService + + +protected void setSecretCallbackHandlerService( SecretCallbackHandlerService secretCallbackHandlerService) { + Logic on Set +} + +protected void unsetSecretCallbackHandlerService(SecretCallbackHandlerService secretCallbackHandlerService) { + Logic on Unset +}</pre> +</p> + +<p></p> + +<p><strong>Logic on Set </strong></p> + +<p></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></p> + +<p><pre>SecretCallbackHandler secretProvider = secretCallbackHandlerService.getSecretCallbackHandler()); + +SecretInformation secretInformation = SecretInformationFactory.createSecretInformation(secretProvider, aliasPassword, passwordPrompt); + +String actualPassword = secretInformation.getResolvedSecret();</pre> +</p> + +<p>Now you can pPass 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 +such as follows - you cannot pass resolved password directly.</p> + +<p></p> + +<p><pre><datasource> + <password>pass</password> + <secretProvider>any implementation of SecretCallbackHandler- class name</secretProvider> +</datasource></pre> +</p> + +<p>You have to do following if the scenario is similar to the above.</p> + +<p></p> + +<p><pre>if (secretCallbackHandlerService != null) { + SecretCallbackHandler secretCallbackHandler = secretCallbackHandlerService.getSecretCallbackHandler(); + SharedSecretCallbackHandlerCache.getInstance().setSecretCallbackHandler(secretCallbackHandler); +}</pre> +Then you have to specify <strong>secretProvider</strong> in the configuration +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> + +<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> +<ul> + <li>keystore - If keys are in a store , it's location </li> + <li>storepass - Password for 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>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 + trusted store </li> + <li>passphrase - if a simple symmetric encryption using a pass phrase shall + be used </li> +</ul> + +<p></p> + +<p>An example </p> + +<p></p> + +<p><pre>ciphertool.bat -source testpass -keystore resources/security/client-truststore.jks -storepass wso2carbon -alias wo2carbon -outencode base64 -trusted</pre> +</p> +</body> +</html> _______________________________________________ Esb-java-dev mailing list [email protected] https://wso2.org/cgi-bin/mailman/listinfo/esb-java-dev
