Hi All,
C5 Carbon Kernel (5.2.0) will consist of a newly designed secure vault
implementation, which was redesigned with the concerns of extensibility.
The default implementation will be based on the JKS, but it will provide
the flexibility to incorporate with external vaults and key managers.
Secure Vault enables component/product developers to keep the secrets
(passwords) in one file "secrets.properties" (where the encrypted passwords
are persisted), with an alias associated with each secret. Configuration
files refer the secrets via aliases and at the runtime these secrets will
be resolved to their original (decrypted) values.
There are two major components in the Secure Vault Implementation;
1. *CipherTool* - Encrypts the secrets given in the "secrets.properties"
file.
2.
*SecureVault* *Component*
-
Decrypts
the secrets
at runtime.
**
*SecureVault* *Component*
Below is a high-level illustration of the Secure Vault Component
There are three main sub-components in the Secure Vault Component. (
*SecretRepository, **MasterKeyReader *and* SecureVault OSGi service*)
*1. SecretRepository* - Secret Repository is responsible for reading the
secrets.properties file, providing the decrypted secrets and providing
encryption/decryption capability depending on the underlying cipher
mechanism.
In the default implementation 'org.wso2.carbon.kernel.secure
vault.repository.DefaultSecretRepository', will expose the secrets given in
the secrets.properties file and provides the encryption/decryption based on
the javax.crypto.Cipher and configured JKS in the secure-vault.yaml file.
If it's needed to implement a custom SecretRepository, one can implement
the 'org.wso2.carbon.kernel.securevault.SecretRepository', register it as
an OSGi service and update the secure-vault.yaml file.
*2. MasterKeyReader* - Master Key Reader is responsible for reading
passwords/keys/etc. that are needed to initialize the SecretRepository.
In the default implementation 'org.wso2.carbon.kernel.secure
vault.reader.DefaultMasterKeyReader', it reads the master keys in several
ways. Following is the order in which the DefaultMasterKeyReader reads the
master keys.
(i). Environment variables
(ii). System variables
(iii). master-keys.yaml file in [product-home]
(iv). command line
If the expected master key values are found in (i), (ii) or (iii), it won't
look into the option (iv).
If it's needed to implement a custom MasterKeyReader, one can implement the
'org.wso2.carbon.kernel.securevault.MasterKeyReader', register it as an
OSGi service and update the secure-vault.yaml file.
*3. SecureVault OSGi service* - Secure Vault OSGi service provides
encryption, decryption and resolve (get the secret from alias)
capabilities. Any component that needs to perform dynamic encryption and
decryption can have a dependency on the
org.wso2.carbon.kernel.securevault.SecureVault
OSGi service and perform the cipher operations.
*Cipher Tool*
Cipher Tool is a stand alone java tool, which reads the configurations from
the *secure-vault.yaml* file and encrypts the secrets given in
*secrets.properties* file. Apart from that, it is capable of encrypting and
decrypting a given text.
Usage: ciphertool.sh [<command> <parameter>]
-- command -encryptText | -decryptText | -customLibPath
-- parameter input to the command
eg:
1. ciphertool.sh
Encrypts the secrets in the conf/security/secrets.properties file
2. ciphertool.sh -encryptText ABC@123
Encrypts the given parameter "ABC@123"
3. ciphertool.sh -decryptText XX...XX
Decrypts the given parameter "XX...XX"
4. ciphertool.sh -customLibPath /home/user/custom/libs
Loads the libraries in the given path first and perform the same operation
as in eg:1.
This is an optional flag.
*Files*
Secure Vault Implementation will mainly dependent on two files.
*1. secure-vault.yaml* - The configuration file for the secure vault. This
is where the SecretRepository, MasterKeyReader and their configurations are
specified.
Following are the default configurations;
secretRepository:
type: org.wso2.carbon.kernel.securevault.repository.DefaultSecretR
epository
parameters:
privateKeyAlias: wso2carbon
keystoreLocation: resources/security/wso2carbon.jks
masterKeyReader:
type: org.wso2.carbon.kernel.securevault.reader.DefaultMasterKeyReader
*2. secrets.properties* - This file contains all the secrets and their
aliases. Basically, the file contains key=value pairs, whether the key is
an alias and value has the following format
[plainText | cipherText] value
Sample entries
Before Encrypting:
wso2.sample.password1=plainText ABC@123
After Encrypting:
wso2.sample.password1=cipherText SnBSWKjtZZOo0UsmOpPRhP6ZMNYTb8
0+BZHRDC/kxNT9ExcTswAbFjb/aip2KgQNaVuIT27UtrBaIv77Mb5sNPGiwy
PrfajLNhSOlke2p8YmMkegx/mG2ytJhJa5j9iMGtCsbMt+SAf85v6kGIiH0g
ZA20qDZ9jnveT7/Ifz7v0\=
With the default implementation, there will be another file named
*master-keys.yaml*;
This file provides the default master keys (keyStorePassword and
privateKeyPassword) which will be read by DefaultMasterKeyReader and used
by DefaultSecretRepository to initialize itself.
Following are the default entries in the *master-keys.yaml*;
permanent: true
masterKeys:
keyStorePassword: wso2carbon
privateKeyPassword: wso2carbon
Options supported by the master-keys.yaml :
(i). permanent: true - whether to have this file permanently or delete
after reading the master keys.
(ii). masterKeys - a list of master keys that are needed to initialize the
SecretRepository.
(iii) relocation - an optional parameter which allows having the master
keys in a different file in a different location. (like temporary mount
path which only available at server startup)
eg: relocation : /dev/sdb1/new-keys.yaml
Thanks,
*Jayanga Dissanayake*
Associate Technical Lead
WSO2 Inc. - http://wso2.com/
lean . enterprise . middleware
email: [email protected]
mobile: +94772207259
<http://wso2.com/signature>
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
