SSLConfiguration Javadoc information

com.ibm.as400

Class SSLConfiguration

java.lang.Object
  |
  +--com.ibm.as400.SSLConfiguration

All Implemented Interfaces:

java.lang.Cloneable, javax.net.ssl.ManagerFactoryParameters

public final class SSLConfiguration
extends java.lang.Object
implements javax.net.ssl.ManagerFactoryParameters, java.lang.Cloneable

This class provides for the specification of the configuration needed by the native iSeries™ JSSE implementation.

The native iSeries JSSE implementation works the most efficiently using a KeyStore object of type "IbmISeriesKeyStore". This type of KeyStore object contains key entries and trusted certificate entries based either on an application identifier registered with the Digital Certificate Manager (DCM) or on a keyring file (digital certificate container). A KeyStore object of this type can then be used to initialize an X509KeyManger and an X509TrustManager object from the "IbmISeriesSslProvider" Provider. The X509KeyManager and X509TrustManager objects can then be used to initialize an SSLContext object from the "IbmISeriesSslProvider". The SSLContext object then provides access to the native iSeries JSSE implementation based on the configuration information specified for the KeyStore object. Each time a load is performed for an "IbmISeriesKeyStore" KeyStore, the KeyStore is initialized based on the current configuration specified by the application identifier or keyring file.

This class can also be used to generate a KeyStore object of any valid type. The KeyStore is initialized based on the current configuration specified by the application identifier or keyring file. Any change made to the configuration specified by an application identifier or keyring file would require the KeyStore object to be regenerated to pick up the change. Note that a keyring password must be specified (for the *SYSTEM certificate store when using an application ID) to be able to successfully create a KeyStore of a type other than "IbmISeriesKeyStore". The keyring password must be specified to successfully gain access to any private key for any KeyStore of type "IbmISeriesKeyStore" which is created.

Since:: SDK 1.4
See Also:: KeyStore, X509KeyManager, X509TrustManager, SSLContext

-------------------------------------------------

Constructor Summary

SSLConfiguration() Creates a new SSLConfiguration. See Constructor detail for more information.

Table 1. **Method Summary**
`void`	clear() Clears all information in the object so that all of the get methods return null.
`java.lang.Object`	clone() Generates a new copy of this SSL configuration.
`boolean`	equals(java.lang.Objectobj) Indicates whether some other object is "equal to" this one.
`protected void`	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`java.lang.String`	getApplicationId() Returns the application ID.
`java.lang.String`	getKeyringLabel() Returns the keyring label.
`java.lang.String`	getKeyringName() Returns the keyring name.
`char[]`	getKeyringPassword() Returns the keyring password.
`java.security.KeyStore`	getKeyStore(char[]password) Returns a keystore of type "IbmISeriesKeyStore" using the given password.
`java.security.KeyStore`	getKeyStore(java.lang.Stringtype, char[]password) Returns a keystore of the requested type using the given password.
`int`	hashCode() Returns a hash code value for the object.
`staticvoid`	(java.lang.String[]args) Executes SSLConfiguration functions.
`void`	(java.lang.String[]args, java.io.PrintStreamout) Executes SSLConfiguration functions.
`void`	setApplicationId(java.lang.StringapplicationId) Sets the application ID.
`void`	setApplicationId(java.lang.StringapplicationId, char[]password) Sets the application ID and the keyring password.
`void`	setKeyring(java.lang.Stringname,java.lang.Stringlabel, char[]password) Sets the keyring information.

-------------------------------------------------

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

-------------------------------------------------

Constructor detail

SSLConfiguration

public SSLConfiguration()

Creates a new SSLConfiguration. The application identifier and keyring information is initialized to default values.

The default value for the application identifier is the value specified for the "os400.secureApplication" property.

The default values for the keyring information is null if the "os400.secureApplication" property is specified. If the "os400.secureApplication" property is not specified, then the default value for the keyring name is the value specified for the"os400.certificateContainer" property. If the "os400.secureApplication" property is not specified, then the keyring label is initialized to the value of the "os400.certificateLabel" property. If neither of the "os400.secureApplication" or "os400.certificateContainer" properties are set, then the keyring name will be initialized to "*SYSTEM".

-------------------------------------------------

Method detail

-------------------------------------------------

main

public static void main(java.lang.String[]args)

Executes SSLConfiguration functions. There are four commands that can be performed: -help, -create, -display, and -update. The command must be the first parameter specified.

The following are the options which may be specified (in any order):

-keystore keystore-file-name: Specifies the name of the keystore file to be created, updated or displayed. This option is required for all commands.
-storepass keystore-file-password: Specifies the password associated with the keystore file to be created, updated, or displayed. This option is required for all commands.
-storetype keystore-type: Specifies the type of keystore file to be created, updated, or displayed. This option may be specified for any command. If this option is not specified, then a value of "IbmISeriesKeyStore" is used.
-appid application-identifier: Specifies the application identifier to be used to initialize a keystore file being created or updated. This option is optional for the -create and -update commands. Only one of the -appid, keyring, and -systemdefault options may be specified.
-keyring keyring-file-name: Specifies the keyring file name to be used to initialize a keystore file being created or updated. This option is optional for the -create and -update commands. Only one of the -appid, keyring, and -systemdefault options may be specified.
-keyringpass keyring-file-password: Specifies the keyring file password to be used to initialize a keystore file being created or updated. This option may be specified for the -create and -update commands and is required when a keystore type other than "IbmISeriesKeyStore" is specified. If this option is not specified, then the stashed keyring password is used.
-keyringlabel keyring-file-label: Specifies the keyring file label to be used to initialize a keystore file being created or updated. This option may only be specified when the -keyring option is also specified. If this option is not specified when the keyring option is specified, then the default label in the keyring is used.
-systemdefault: Specifies the system default value is to be used to initialize a keystore file being created or updated. This option is optional for the -create and -update commands. Only one of the -appid, keyring, and -systemdefault options may be specified.
-v: Specifies that verbose output is to be produced. This option may be specified for any command.

The help command displays usage information for specifying the paramters to this method. The parameters to invoke the help function is specified as follows:

    -help

The create command creates a new keystore file. There are three variations of the create command. One variation to create a keystore based on a particular application identifier, another variation to create a keystore based on a keyring name, label, and password, and a third variation to create a keystore based on the system default configuration.

To create a keystore based on a particular application identifier, the -appid option must be specified. The following parameters would create a keystore file of type "IbmISeriesKeyStore" named "keystore.file" with a password of "keypass" which is initialized based on the application identifier "APPID":

    -create -keystore keystore.file -storepass keypass -storetype IbmISeriesKeyStore 
            -appid APPID

To create a keystore based on a particular keyring file, the -keyring option must be specified. The -keyringpass and keyringlabel options may also be specified. The following parameters would create a keystore file of type "IbmISeriesKeyStore" named "keystore.file" with a password of "keypass" which is initialized based on the keyring file named "keyring.file", keyring password "ringpass", and keyring label "keylabel":

    -create -keystore keystore.file -storepass keypass -storetype IbmISeriesKeyStore
            -keyring keyring.file -keyringpass ringpass -keyringlabel keylabel

To create a keystore based on the system default configuration, the -systemdefault option must be specified. The following parameters would create a keystore file of type "IbmISeriesKeyStore" named "keystore.file" with a password of "keypass" which is initialized based on the system default configuration:

    -create -keystore keystore.file -storepass keypass -systemdefault

The update command updates an existing keystore file of type "IbmISeriesKeyStore". There are three variations of the update command which are identical to the variations of the create command. The options for the update command are identical to the options used for the create command. The display command displays the configuration specified for an existing keystore file. The following parameters would display the configuration specified by a keystore file of type "IbmISeriesKeyStore" named "keystore.file" with a password of "keypass":

    -display -keystore keystore.file -storepass keypass -storetype IbmISeriesKeyStore

Parameters:: args - the command line arguments

-------------------------------------------------

run

public void run(java.lang.String[]args,
                java.io.PrintStreamout)

Executes SSLConfiguration functions. The parameters and functionality of this method are identical to the main() method.

Parameters:: args - the command arguments; out - output stream to which results are to be written

See Also:com.ibm.as400.SSLConfiguration.main()

-------------------------------------------------

getApplicationId

public java.lang.String getApplicationId()

Returns the application ID.

Returns:: the application ID.

-------------------------------------------------

getKeyringName

public java.lang.String getKeyringName()

Returns the keyring name.

Returns:: the keyring name.

-------------------------------------------------

getKeyringLabel

public java.lang.String getKeyringLabel()

Returns the keyring label.

Returns:: the keyring label.

-------------------------------------------------

getKeyringPassword

public final char[] getKeyringPassword()

Returns the keyring password.

Returns:: the keyring password.

-------------------------------------------------

finalize

protected void finalize()
                 throws java.lang.Throwable

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Overrides:: finalize in class java.lang.Object
Throws:: java.lang.Throwable - the exception raised by this method.

-------------------------------------------------

clear

public void clear()

Clears all information in the object so that all of the get methods return null.

-------------------------------------------------

setKeyring

public void setKeyring(java.lang.Stringname,
                       java.lang.Stringlabel,
                       char[]password)

Sets the keyring information.

Parameters:: name - the keyring name; label - the keyring label, or null if the default keyring entry is to be used.; password - the keyring password, or null if the stashed password is to be used.

-------------------------------------------------

setApplicationId

public void setApplicationId(java.lang.StringapplicationId)

Sets the application ID.

Parameters:: applicationId - the application ID.

-------------------------------------------------

setApplicationId

public void setApplicationId(java.lang.StringapplicationId,
                             char[]password)

Sets the application ID and the keyring password. Specifying the keyring password allows any keystore which is created to allow access to the private key.

Parameters:: applicationId - the application ID.; password - the keyring password.

-------------------------------------------------

equals

public boolean equals(java.lang.Objectobj)

Indicates whether some other object is "equal to" this one.

Overrides:: equals in class java.lang.Object
Parameters:: obj - object to be compared
Returns:: indicator of whether the objects specify the same configuration information

-------------------------------------------------

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:: hashCode in class java.lang.Object
Returns:: a hash code value for this object.

-------------------------------------------------

clone

public java.lang.Object clone()

Generate a new copy of this SSL configuration. Subsequent changes to the components of this SSL configuration will not affect the new copy, and vice versa.

Overrides:: clone in class java.lang.Object
Returns:: a copy of this SSL configuration

-------------------------------------------------

getKeyStore

public java.security.KeyStore getKeyStore(char[]password)
                                   throws java.security.KeyStoreException

Returns a keystore of type "IbmISeriesKeyStore" using the given password. The keystore is intialized based on the configuration information currently stored in the object.

Parameters:: password - used to initialize the keystore
Returns:: KeyStore keystore initialized based on the configuration information currently stored in the object
Throws:: java.security.KeyStoreException - if the keystore could not be created

-------------------------------------------------

getKeyStore

public java.security.KeyStore getKeyStore(java.lang.Stringtype,
                                          char[]password)
                                   throws java.security.KeyStoreException

Returns a keystore of the requested type using the given password. The keystore is initialized based on the configuration information currently stored in the object.

Parameters:: type - type of keystore to be returned; password - used to initialize the keystore
Returns:: KeyStore keystore initialized based on the configuration information currently stored in the object
Throws:: java.security.KeyStoreException - if the keystore could not be created