Wednesday, July 24, 2013

Managing WSM Key Store and Credential Store

I am working on a series of OWSM related posts. This one talks about the OWSM key store and credential store. Specifically, this post mostly talks about the physical aspects of the stores: where the files are, how to use UI to find and manage them. I will cover how to generate, export/import, work with aliases of keys and certs etc.

OWSM's key store and credential store are always mysterious to me. As i get better understanding them, i'm recording what i have learned.

By default, OWSM key store (also referred to as OWSM agent's key store) is here: "<domain home>/config/fmwconfig/default-keystore.jks". The actual location can be found in this file: <domain home>/config/fmwconfig/jps-config.xml.

You can configure the keystore from the "em" console, expand "Weblogic Domain" on the left, then right click your domain, select "security", then "security provider configuration", and on that page, click "configure" button under the "Keystore" section.


There are many key stores in SOA suite. This one is for OWSM. It uses the certificates in the store for encryption/decryption when processing OWSM security policies. Do not confuse this keystore with the ones for Weblogic server. Those are under Weblogic console->"Environment"->"servers"-> "your server", then under the "Keystores" tab. You will see at least two "identity" and "trust" stores. Those stores contain certificates mostly for the server SSL among other things.

Based on my observation, when a domain is first created, although "em" console, security provider store configuration page shows the file is "./default-keystore.jks", that file doesn't even exist. You need to use java "keytool" command to generate the file. For example,

keytool -genkeypair -alias test_domain_alias  -keyalg RSA -keypass welcome2 -keystore test_domain.jks  -storepass welcome1 -validity 3650

it will prompt you for your name, location etc, then it will generate a test_domain.jks file. This file contains public/private keys that can be used for encryption/decryption. The key alias is "test_domain_alias" (pay attention to this alias, as it is related to the credential stores we'll discuss). The keypass (for test_domain_alias) is "welcome2". The keystore password is "welcome1", which is used to access the store file. 3650 will make key valid for 10 years!

For example, keytool -list -v -storepass welcome1 -keystore test_domain.jks, will display the certificate contained in the key store.

Once the test_domain.jks file is created, you can put it in the default place (or other place as you choose) under "${your domain home}/config/fmwconfig", then you can configure the store as shown below:

Please note that we used test_domain.jks as the keystore path, the password is "welcome1". For Signature and Encryption key alias, we entered "test_domain_alias". We use "welcome2" for both passwords. Please be careful that the editor doesn't validate anything you enter here other than "password and confirm password" are the same. You can enter wrong jks name, wrong passwords, and wrong alias, it would just same them as-is. I guess you'll find out things are not working at run time if you saved incorrect information.

So where is all the information you entered stored? They all went to the credential store. I believe the physical file is cwallet.sso, it's a binary file, you can't see much of it.

What is the credential store then? Well, all I know is that it stores some "credentials", such as user name and password. Each entry has a key. The overall credential store is organized by "maps".

You access the credential store as shown in the first picture above. Here is a sample view:


If you already configured the key store as above, you will see at least one "oracle.wsm.security" map, under the map, you'll see at least 3 keys: sign-csf-key, enc-csf-key, and keystore-csf-key. These are populated when you configured the keystore. If you change them here (for example, edit sign-csf-key, try change the value from "test_domain_alias" to something else), and you go back to the keystore configuration, you'll notice it is updated over there as well. Again, it's garbage in garbage out, whatever you enter, it would be saved as-is. It's your responsibility to enter the info correctly. If you go to the extreme and delete the oralce.wsm.security map here, then go the keystore configure, you'll see the data is wiped out over there and you'll have to reconfigure the keystore.

BTW, how does OWSM know to use these 3 special keys to access the store. If you open fmwconfig/jps-config.xml, you'll find them there.

That's quite enough about these 3 keys! Let's look at the other key i created manually, "basic.credentials". Under the key i have user name "weblogic", password "welcome1". This is typically used like a "service account", if a BPEL or OSB business process need to invoke another service and provide a service account, you can simply reference "basic.credentials" under oracle.wsm.security. It just so happened that several OWSM security policy reference this particular key "basic.credentials" by default. For example,if you have oracle/wss_username_token_service_policy on a proxy and run the test console on the proxy, you'll see it uses "basic.credentials" by default.


I think oracle/wss_username_token_client_policy does the same, at least for SOA client, it uses "basic.credentials" for user/pass if you don't explicitly specify them in your code.If your key name is something different, then your process needs to reference the other name.

OWSM Note - When import certs, remember to bring in the chain if neccessary

OWSM has so many aspects, it's impossible to discuss OWSM in a few posts. So I'm splitting things up and add specific notes as I go.
Context: I am running test with SAML policy with msg protection on two hosts. The client server has a key store contains its private key “foo”, and server contains private key “bar”.
BTW, OWSM key store, by default, is under <domain home>/config/fmwconfig/default-keystore.jks. The actual location can be found in <domain home>/config/fmwconfig/jps-config.xml.
After I exchanged the certs of the two servers, the picture looks like:
·        Client key store: client private key “foo”, imported server cert “bar
·        Server key store: server private key “bar”, “bar CA”, imported client cert “foo”
when I ran the test, the client side log file produces this:
<Error> <oracle.wsm.resources.security> <WSM-00138>
The path to the certificate is invalid due to Path does not chain with any of the trust anchors .
Validation failed for certificate "CN=bar, OU=Application Development & Architecture, O=ACME Inc., L=Phoenix, ST=Arizona, C=US" Issuer of certificate is "C=US, ST=Arizona, L=Phoenix, O="ACMEInc.", OU=Application Development & Architecture, CN=bar CACertificates in cert path used for validation are  CN=foo, OU=Application Development & Architecture, O=ACME Inc., L=Phoenix, ST=Arizona, C=US.
Looking at key store picture above, it appears that I have exchanged keys “foo” and “bar” properly. So we do I get cert errors? After closely examine the errors messages and the key stores, I found out the problem is the cert I imported into the client store was not a root CA cert. I need to import the server cert as well as it's CA. Here is the new picture:
·        Client key store: client private key “foo”, imported server cert “bar”, imported server “bar CA” cert
·        Server key store: server private key “bar”, “bar CA”, imported client cert “foo
The revealing parts of the error message are “path to the certificate” and “chain”. That leads me to examine the key stores. I noticed that server cert “bar” shows “Certificate chain length: 2”, and finally I realized importing “bar” alone to the client store without its CA is causing the problem. The solution is to import “bar CA” into the client store as well. That took care of the problem.
Let me list all the keytool commands I use to diagnose and resolve the issue. Keytool is under Java bin directory.
Generate key pair:
keytool -genkeypair -alias foo  -keyalg RSA -keypass welcome1 -keystore client-keystore.jks  -storepass welcome1 -validity 3650
I am getting into the habit to set validity to 10 years (3650 days). I ran into too many times of using the default of 1 year, then my test server stops running after a year, and took me long time to find out why.
Keep in mind, alias “foo” is only a local alias in this key store, when you export “foo”, then re-import it into another store, you can give it a different alias, say for example, call it “client_foo”.
Examine the key store:
keytool -list -v -storepass welcome1 -keystore client-keystore.jks
When I ran this command on the server key store, I saw the server cert has a key length of 2. I also found the CA for the server cert in the same key store.
Export cert:
keytool -exportcert -alias foo -keystore client-keystore.jks -storepass welcome1 -file client_foo.cer
Import cert:
keytool -importcert -alias client_foo -keystore server_keystore.jks -storepass serverKeyPass -file client_foo.cert
Import CA cert:
keytool -importcert -trustcacerts -alias "bar CA" -keystore client-keystore.jks -storepass welcome1 -file bar-ca.cer
If the cert you import is chained to a CA (or more), you need to import CA certs.