You can use key sets to manage multiple instances of cryptographic
keys. WebSphere® Application Server uses keys
to encrypt or sign outbound data, and decrypt or verify inbound data
during cryptographic operations.
Before you begin
You must have write-access to the keystore that will contain
the keys after you generate them from a key set. However, if you want
to generate keys outside of WebSphere Application Server,
you can reference the keys from a read-only keystore that contains
a secret key that you can access when you generate the keys. If you
are creating a key pair using an X509Certificate and a PrivateKey
object , see
Example: Developing a key or key pair generation class for automated key generation.
About this task
Complete the following steps in the administrative console:
Procedure
- Decide whether you want to create the key set at the cell
scope or below the cell scope at the node, server, or cluster, for
example:
- To create a key set at the cell scope, click Security >
SSL certificate and key management > Key sets.
- To create a key set at a scope below the cell level, click Security >
SSL certificate and key management > Manage endpoint security configurations >
{Inbound | Outbound} > ssl_configuration > Key
sets.
- Click New to create a new key set.
- Type a key set name. For example, CellmyKey.
- Type a key alias prefix name. For example, myKey. This field specifies the prefix for the key alias when the new
key is generated and stored in the keystore. Following the prefix
is the key reference version number, for example, 2, so that the full
key alias name would be myKey_2. If the key reference already
has a specified alias for a key that exists in the keystore, then WebSphere Application Server ignores this
field.
- Type a key password. The key password protects
the key in the keystore. This password is ignored by WebSphere Application
Server if you already specified a password for the key alias reference.
To check for a key reference password, click Active key history under
Additional Properties. The key reference password protects keys that
are generated by a key generator class.
- Type the password again to confirm it.
- Optional: Type the key generator class name.
For example, com.ibm.ws.security.ltpa.LTPAKeyGenerator. The class name generates keys. If the class implements com.ibm.websphere.crypto.KeyGenerator,
then a getKey method returns a java.security.Key object that is set
in the keystore using the setKey method without a certificate chain.
If the class implements com.ibm.websphere.crypto.KeyPairGenerator,
then a getKeyPair method returns a com.ibm.websphere.crypto.KeyPair
object that contains either a java.security.PublicKey and java.security.PrivateKey
or a java.security.cert.Certificate and a java.security.PrivateKey
object. The key generator class and the KeySetHelper API specify the
details of the keys that are generated.
- Optional: Select Delete key references that
are beyond the maximum number of keys if you do not want old
keys saved in the keystore after WebSphere Application
Server removes their references from the Active key history listing. The Active key history lists the keys that the KeySetHelper
API is currently tracking. The number of keys in the list is equal
to the number of keys that you specify in Maximum number of keys
referenced.
- Type a numeric value for the maximum number of keys referenced. For example, if you type 3 and select Delete key
references that are beyond the maximum number of keys, the fourth
key version generation automatically triggers WebSphere Application
Server to delete the first key version from the keystore. If you choose
not to delete the old keys, they do not display in the Active key
history list but instead remain in the keystore where you can remove
them manually.
- Select a keystore from the drop-down list.
- Select a JCEKS keystore if you are storing a secret key.
- Select any keystore if you are storing a key pair with an
X509Certificate and PrivateKey object.
- Optional: Select Generates key pair if
your key generator class name implements the com.ibm.websphere.crypto.KeyPairGenerator
interface instead of the com.ibm.websphere.crypto.KeyGenerator interface. This option designates that the key references a key pair instead
of a single key. A key pair contains both a public key and a private
key. The WebSphere Application Server run time determines
whether or not key pairs are stored and loaded differently than single
keys.
- Optional: Click Apply if you want to
select Active key history under Additional Properties to add
alias references or generate more keys.
- Click Active key history.
- Click Add key alias reference if you are not
using the key generator class name to add key alias references to
the keys that already exist in the keystore. Use this option to retrieve
the keys from a read-only keystore without the key set generating
them.
- Type an alias reference.
- Click Generate key if you want to generate a
key using the class name that you defined in the key sets panel. Each new key increments numerically, for example, myAlias_2.
- Click Apply.
- Click the key set name in the navigation path at the top
of the panel.
- Click OK and Save.
Results
You have created a key set that you can manage using the
Active
key history link. You can generate keys manually to associate
them with specified key sets.
What to do next
After you generate new keys from a key set, you can access
them programmatically using the com.ibm.websphere.crypto.KeySetHelper
API. You must have Java 2 Security permissions, if
enabled, to access keys in key sets. Specify the key set name within
the fine-grained permissions, as in the following code sample:
WebSphereRuntimePermission
"getKeySets.keySetName". For more information, see
Example: Retrieving the generated keys from a key set group. To generate
multiple key types at the same time or to schedule the key generation
on a specific schedule, see
Creating a key set group configuration.