Add your own keystore in WSO2 Server

In this post i'll explian how you can add your own keystore in wso2 server.

All WSO2 servers comes with a default keystore named wso2carbon.jks. This keystores are used to hold the certificates/keys used for SSL communication and data encription of passwords. There are situations that you need to replace this wso2carbon.jks with your keystore.

Here i'll explain the minimum modifications you need to follow to add your keystore.

You can find the wso2carbon.jks  under WSO2Server/reposotory/resourses/security. And configuration details for this is listed in  WSO2Server/reposotory/conf/carbon.xml as follows

           

            ${carbon.home}/repository/resources/security/wso2carbon.jks

            

            JKS

            

            wso2carbon

            

            wso2carbon

            

            wso2carbon

        

Also in  WSO2Server/repository/conf/security/secret-conf.properties you can see following configurations

##KeyStores configurations
#
#keystore.identity.location=repository/resources/security/wso2carbon.jks
#keystore.identity.type=JKS
#keystore.identity.alias=wso2carbon
#keystore.identity.store.password=wso2carbon
##keystore.identity.store.secretProvider=
#keystore.identity.key.password=wso2carbon


As you have seen above when you chnage the keystore, you have to chenge the configs of following files accordingly. (Note that thiis is the minimal configuration, you may have to change in other places if you have used this keystore)

• WSO2Server/reposotory/conf/carbon.xml
• WSO2Server/repository/conf/security/secret-conf.properties
• WSO2Server/repository/conf/sec.policy
• WSO2Server/repository/conf/security/cipher-text.properties

Additionally you mey need to change the entries of following files depending on the product (eg ESB) and version you use.

• WSO2Server/repository/conf/tomcat/catalina-server.xml
• WSO2Server/reposotory/conf/axis2/axis2.xml

Initial content of the WSO2Server/repository/conf/security/cipher-text.properties file

# This is the default file based secret repository, used by Secret Manager of synapse secure vault
# By default, This file contains the secret alias names Vs the plain text passwords enclosed with '[]' brackets
# In Production environments, It is recommend to replace those plain text password by the encrypted values. CipherTool can be used for it.

Carbon.Security.KeyStore.Password=[wso2carbon]
Carbon.Security.KeyStore.KeyPassword=[wso2carbon]
Carbon.Security.TrustStore.Password=[wso2carbon]
UserManager.AdminUser.Password=[admin]
Datasources.WSO2_CARBON_DB.Configuration.Password=[wso2carbon]


Create a KeyStore with keytool

To work with wso2server you can create your key with following format.

keytool -genkey -keystore susinda.jks -keyalg RSA -alias susinda  -ext ku=dataEncipherment,digitalSignature,nonRepudiation,keyEncipherment
Note : Here(while you create the keystore) you have to provice the keypassword same as the keystore password


keytool -list -v -keystore  susinda.jks 
Enter keystore password:  
Give your keystore password here, then you can see the comand output as follows.


Keystore type: JKS
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: susinda
Creation date: Jul 15, 2014
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Susinda, OU=susiOU, O=susiORG, L=Colombo, ST=Srilanka, C=SL
Issuer: CN=Susinda, OU=susiOU, O=susiORG, L=Colombo, ST=Srilanka, C=SL
Serial number: 50eed9f5
Valid from: Tue Jul 15 10:33:49 IST 2014 until: Mon Oct 13 10:33:49 IST 2014
Certificate fingerprints:
MD5:  54:9E:71:11:F5:81:2D:4E:58:E1:72:4D:B0:E8:19:1D
SHA1: D5:86:16:42:3D:18:88:79:E9:D8:34:17:C6:A9:39:33:5A:62:24:95
SHA256: 44:2B:48:F2:1F:66:10:B9:37:95:EB:11:59:FF:AA:A1:A4:1A:6D:E0:19:C9:0A:6F:72:57:5D:F0:1D:CC:19:72
Signature algorithm name: SHA256withRSA
Version: 3

Extensions: 

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 5F 70 2F AD DB DC 5A 1B   A2 A6 AE 72 04 B1 80 29  _p/...Z....r...)
0010: 5B E1 4A 8E                                        [.J.
]

*******************************************

Encript sensitive data with ciphertool

In wso2 servers there is a tool called cipher-tool to encription nad decription purposes This tool use the keystore defined in carbn.xml for encript. You can find this under WSO2Server/bin/


To run this toool use the comand  ./ciphertool.sh -Dconfigure, Then it will prompt following

[Please Enter Primary KeyStore Password of Carbon Server : ]

Here give the password that you have provided for your keystore, then you see the command output as follows.

Primary KeyStore of Carbon Server is initialized Successfully

Protected Token [Carbon.Security.TrustStore.Password] is updated in carbon.xml successfully

Protected Token [Carbon.Security.KeyStore.KeyPassword] is updated in carbon.xml successfully

Protected Token [UserManager.AdminUser.Password] is updated in user-mgt.xml successfully

Protected Token [Datasources.WSO2_CARBON_DB.Configuration.Password] is updated in master-datasources.xml successfully

Protected Token [Carbon.Security.KeyStore.Password] is updated in carbon.xml successfully

Encryption is done Successfully

Encryption is done Successfully

Encryption is done Successfully

Encryption is done Successfully

Encryption is done Successfully

Secret Configurations are written to the property file successfully

Now if you looked at carbon.xml you may see that password has been chnaged as Password svns:secretAlias="Carbon.Security.KeyStore.KeyPassword".

            

            ${carbon.home}/repository/resources/security/susinda.jks

            

            JKS

            

            password

            

            susinda

            

            password

        

In secret-conf.properties file it has chaged as follows

keystore.identity.location=/home/susinda/wso2as-5.2.1/repository/resources/security/susinda.jks
keystore.identity.type=JKS
keystore.identity.store.password=identity.store.password
keystore.identity.store.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler
secretRepositories.file.provider=org.wso2.securevault.secret.repository.FileBaseSecretRepositoryProvider
secretRepositories.file.location=repository/conf/security/cipher-text.properties
secretRepositories=file
keystore.identity.key.password=identity.key.password


If you looked at /security/cipher-text.properties file you can see the encipted values.

Carbon.Security.KeyStore.Password=D8GH2NqKEQyW8BKB51PluBmTDTaILUWlS6aTTz6sQJgIj4ExgZ4SZxiFsuJJhFFiVDzj4xqAun09\n6+X7Q4zerCHlJhvdh4E6GEJXtWsuoqz/66JpJ4Jtp/nEpKDs1j49T0KrxERAQ9frPRwpXJNqeLQr\nyKU1mngasfbdfo88xwM8dRgsP5fV//3gbSOiEKu1e5jFdXvIkGT8BKAx0rKsVzzwCyUassggmd4V\nlc/TxlVoz3s69ZOg85T9n1wVkP6N40Kn4U8EqX++oeeIWX404pUR9uqekuTDY+JHfZ22DMm6+HlT\nhfedxc1Q23IyWTcN728IBe2l9R3DqOagB8RuAQ\=\=
Carbon.Security.KeyStore.KeyPassword=FxfyvDztx4e4NgLUh7Zzhbv+dOPBbsLUI9fwJx6N0eitsaNq6+cijD2mht8S8AXWDRkFu89Fdnrb\nf5/8IHx4rKQ1zsAShj/UYwvT9nShHlLYc4qjyvY/IkbKkjY+Fhs03nzJMKM1Kza242EWcrGshCpu\nLiy60pqdIOt1ipsFXY232qdVWSYCuDTxWq6JAkfQtScheGbPaRRNQZFXD7bPl8g4r7DB3s9W+X8w\nWCyDUatdOHmVEc4sVYnbN1aXs8pyHOjeEUITkskTCRQHJwCaAaADkwTGg+iCJuRXd8WdmvBOLyda\ng4QdU8cYwNy0kbf7cy8MRPtC+jdRl47zi3jddA\=\=

Once you sart the server it will ask your keystore password.

[Enter KeyStore and Private Key Password :]

Special note on Keystore and Registrykeystore
The primary keystore mainly stores the keys certifying SSL connections to Carbon servers and the keys for encrypting administrator passwords as well as other confidential information.

RegistryKeyStore is a separate keystore element configurable in the carbon.xml file. This configuration applies for the keystore which stores the keys that certify encrypting/decrypting meta data to the registry. Therefore, using the registry keystore in addition to the primary keystore in the carbon.xml file allows you to maintain a separate keystore for the purpose of encrypting/decrypting meta data to the registry.
http://docs.wso2.com/pages/viewpage.action?pageId=31884668

Adding a Registrykeystore
Add following properties in cipher-tool.properties file
Carbon.Security.RegistryKeyStore.Password=carbon.xml//Server/Security/RegistryKeyStore/KeyPassword,true

Carbon.Security.RegistryKeyStore.KeyPassword=carbon.xml//Server/Security/RegistryKeyStore/Password,true

Also add following in cipher-text.properties file
Carbon.Security.RegistryKeyStore.KeyPassword=[regkeypassword]

Carbon.Security.RegistryKeyStore.Password=[regkeypassword]

Note : For additional information you can rever "Secure plain text passwords in WSO2 Carbon configuration files" @ http://soasecurity.org/2012/08/12/secure-plain-text-passwords-in-wso2-carbon-configuration-files/

Run cipher tool

Run the server 
Give the regkeypassword, when it is asked for primary password