Implementing the KeyStore Service with Fusion MiddleWare 12c

For the passphrases, use the passphrases used earlier.Thinking about TLS (Transport Layer Security, the succesor of Secure Socket Layer, SSL) and WebLogic and Oracle HTTP Server, allways gave me Cold Water Fear. You have to create keystores with keys, wallets, certificate signing requests, import signed and trusted certificate chains. Not to mention the configuration of WebLogic and OHS.

Now, creating keystores with the Java Keytool turns out not that hard. And generating the Certificate signing requests and importing the certificates are also a walk in the park, nowadays. The internet world is full of example so I'm not going to do that here.

But lately, our Service Bus developers found that they needed to replace the configured demo identity and trust key stores with Custom Stores. But this broke the connection between the AdminServer and the Nodemanagers, resulting in TLS/SSL Handshake errors. By default, the nodemanagers work with the demo-identities when running in TLS.

This drove us to work out an infrastructural configuration of TLSin our FMW environments, in a  way that the SB developers can extend that with their certificates.

In this article I want to describe how to configure TLSin Weblogic using the KeyStore Service, and also how to reconfigure the nodemanagers to have them running TLS using the custom stores.

Keystores and the KeyStore Service (KSS)

When implementing in TLS in Fusion MiddleWare 12c you have the choice to use the new KeyStore Service for creating keys and certificates directly in the KSS, or the Java Key Tool.

Until now WebLogic preferred a Java Key Store (JKS) for storing certificates. This is a file that functions as a vault to store your keys and certificates savely. You can use the commandline tool Keytool that is delivered with the JDK. But there are several graphical tools, like Portecle, that can make your encrypting life even more simple.

Since a keystore is a atomic file, you need to copy it or put it on a share to have a complete multi-node clustered domain use the same store.

Per Fusion MiddleWare 12c Oracle introduced the KeyStoreService. The KSS is part of the Oracle Platform Security Services, and stores the keys in so-called Stripes in the MDS. For some components it is necessary to sync them to a keystores.xml file in the domain. But we'll get to that.
The KSS enables you to create, delete and manage keystores from the Enterprise Manager/FustionMiddleWare Control.

As said, you can start with creating your keys using the KSS. We however did choose not to. We started with creating a JKS using the KeyTool. The reaons for that were:

• Using the keytool, you can already create a store and a Certificate Signing Request (CSR) before configuring your domain.
• We wanted to make sure we had the configuration of Weblogic and Nodemanager correct, before transition to KSS. 
• With a JKS you have a backup of your identity in case you mess up your configuration. Keep in mind that you need to import the CSR into the keystore from where you generated the key. Even a new JKS created the exact sameway won't work.
• Using OraPKI, you can migrate your certificates from a JKS to a wallet. We are still in the 'figure-out-phase' of implementing OHS with KSS.
• Oh, and we wanted to have scripts and easy to document commands for creating and importing the stores.

Identity and Trust Store

So we started with creating  an Identity Keystore with the Java Keytool, created a CSR and had it signed.
We had several virtual hostnames refering to the hostname (darlin001.org.darwin-it.local) loadbalancer (o-dwn-1.ont.org.darwin-it.local), managed servers (o-dwn-1-dwn-1-vhn.ont.org.darwin-it.local), Admin Virtual host (o-dwn-1-admin-vhn.ont.org.darwin-it.loca), etc. To have them accepted with the same certificate, you need to create the Certificate Signing Request with an extention called 'Subject Alternative Names'. This can be done with the -ext parameter including the SAN keyword as follows:

... -ext SAN=dns:darlin001.org.darwin-it.local,dns:o-dwn-1-admin-vhn.ont.org.darwin-it.local,dns:o-dwn-1-dwn-1-vhn.ont.org.darwin-it.local,dns:o-dwn-1-dwn-2-vhn.ont.org.darwin-it.local,dns:o-dwn-1-ohs-1-vhn.ont.org.darwin-it.local,dns:o-dwn-1-internal.ont.org.darwin-it.local,dns:o-dwn-1-admin.ont.org.darwin-it.local,dns:o-dwn-1.ont.org.darwin-it.local

This is a comma seperated list, with each addres need to be prefixed with dns:. See also the keytool documentation.

Don't forget to add the Common Name (CN) to the SAN, since clients are supposed to ignore the CN, when using a SAN. Also you need to add the -ext SAN parameter to the CSR. You can use it when creating the Key, but that's not enough for the CSR.

For the Trust Store, I copied the cacerts from the JDK. I changed the password and imported the CA and root certificates. But you need to consider if you want to accept all the JDK's trusted certificates. Or only those you really need to trust.

 Scope of the Keystore

We choose to have the domain the scope of the keystore, not the host. So as a CommonName I choose the loadbalancer address. The thing is that we want to have the managed servers use the same keystore. And with a whole server migration, a managed server could migrate to a new host, that is not yet in the certificate. Although we add the known hosts, we could be forced to use a new host. And with whole server migrations, you can't way for your CSR to be signed.
As name of the keystores and the identity alias I choose a reference to our domain name. As an environment shortage I choose 'dwn', that could also refer to the type of environment. Like BPM, OSB, SOA, etc. The first letter ('o') denotes the development environment (Dutch: 'ontwikkeling'). And the digit denotes the environment number, where you could have multiple development or test environment.

Import KeyStores into KSS

Having created your KeyStores and made sure Weblogic works with them, you can import them into the KSS. The UI (EM) does allow you to create a keystore, and import certificates. It does not allow you to import a complete JKS. But you can do so using WLST. This caters also for my quest to script as much as possible.

The commands are executed in WLST Online mode, connected to the AdminServer. So start wlst and connect to the AdminServer.

In the following command commands, I use the following environment variables:

• $JAVA_HOME: refering to, yes, you're right....
• $JKS_LOC=/u01/oracle/config/keystore
• $JKS_NAME=o-dwn-1.jks
• $JKS_TRUST_NAME=o-dwn-1-trust.jks

Connected to your AdminServer you need to get a handle on the 'KeyStoreService object', that has methods to do the imports,  etc.:

wls:/o-dwn-1_domain/serverConfig/> svc = getOpssService(name='KeyStoreService')

With the handle you can import the Identity keystore:

wls:/o-dwn-1_domain/domainRuntime/> svc.importKeyStore(appStripe='system', name='o-dwn-1-id', password='<password>', aliases='o-dwn-1', keypasswords='<password>', type='JKS', permission=false, filepath='/u01/oracle/config/keystore/o-dwn-1.jks')
Already in Domain Runtime Tree 

Keystore imported. Check the logs if any entry was skipped.

The parameters aliases and keypasswords contain a comma-separated list of key-aliases and corresponding key-passphrases.
My advise would be to use the same password for your key as for your keystore. Many products (like Oracle B2B) allow you to provide only one password, that is used for both.

Importing the Trust Store, works similar:
svc.importKeyStore(appStripe='system', name='o-dwn-1-trust', password='<password>', aliases='ca_dwn_org,our-root-ca', keypasswords='none,none', type='JKS', permission=false, filepath='/u01/oracle/config/keystore/o-dwn-1-trust.jks')
Already in Domain Runtime Tree

Keystore imported. Check the logs if any entry was skipped.

One thing with Trusts: they don't contain Keys. So no keyprases are applicable. But the keypasswords property is mandatory and also need to contain the same number of passphrases as there are aliases named to be imported in the KSS. Apparently it is sufficient to use 'none' as a passphrase.

A wallet can also be imported the same way. For a type then choose 'OracleWallet', and in filepath a reference to the wallet folder.

To check the content of the keystore, we can list it:

wls:/o-dwn-1_domain/domainRuntime/> svc.listKeyStoreAliases(appStripe="system",name="o-dwn-1-id",password='<password>',type="*")
Already in Domain Runtime Tree

o-dwn-1

And for the trust:

wls:/o-dwn-1_domain/domainRuntime/> svc.listKeyStoreAliases(appStripe="system",name="o-dwn-1-trust",password='<password>',type="*")
Already in Domain Runtime Tree

ca_dwn_org
our-root-ca

Now the keystores are in the KSS. You can see them in EM. But some FMW components like nodemanagers, (but it appeared to me even Weblogic Servers), don't work right away. They can't look into the KSS, but use a keystores.xml file in the ${DOMAIN_HOME}/config/fmwconfig. This turns out to be an export of the keystores. To synchronize the KSS with that file you need to do:

wls:/o-dwn-1_domain/domainRuntime/> syncKeyStores(appStripe='system',keystoreFormat='KSS')
Already in Domain Runtime Tree

Keystore sync successful.

List the content of KSS with FMW Control

To list the KSS within FMW Control, logon and navigate to Weblogic Domain -> Security -> Keystore:

This brings you to the content of the KSS with the particular Stripes. For Weblogic we used the system stripe to import our custom keystores:

Select a store, and click the manage button in the bar. It will ask for the keystore password (the one you used creating the JKS with the keytool). Then it shows:

Here you can import, export certificates, create keypairs and generate a CSR for it.

Reconfigure Weblogic

Now we can proceed in configuring Weblogic and the nodemanagers.

For the weblogic servers, logon to the Admin console, navigate to the particular Server, tab Keystores and select 'Custom Identity Keystore and Custom Trust keystore' in the pop-list.

Then enter the following values:

Attribute	Value
Custom Identity Keystore	kss://system/o-dwn-1-id
Custom Identity Keystore Type	KSS
Custom Trust Keystore	kss://system/o-dwn-1-trust
Custom Trust Keystore Type	KSS

For the passphrases, use the passphrases used earlier.
Then on the SSL tab you can provide the Identity alias and the key-passphrase.

Restart the Server (or at least Restart the SSL, under the control tab).

Reconfigure Nodemanagers for KSS

For the nodemanager, navigate to the nodemanager.properties file in ${DOMAIN_HOME}/nodemanager.
At the top of the file add the following properties:

KeyStores=CustomIdentityAndCustomTrust
CustomIdentityKeyStoreFileName=kss://system/o-dwn-1-id
CustomIdentityKeyStoreType=KSS
CustomIdentityKeyStorePassPhrase=
CustomIdentityAlias=o-dwn-1
CustomIdentityPrivateKeyPassPhrase=

Restart the nodemanager and check if it succesfully loads the kss://system/o-dwn-1-id as a keystore and starts the listener in SSL mode.

Then in the AdminServer console, under Domain Structure -> Machines -> <Machine_Name> check if the NodeManager is 'Reachable'.

Conclusion

That's about it. Don't forget to Sync the KSS in wlst, when the nodemanager does not restart properly and the managed/admin server could not start SSL properly.

 I hope I'll soon be able to write down the directions to reconfigure SSL in OHS to use the KSS. But as said we're still in the 'figure-out-phase'.