com.ibm.as400.access

Class AS400CertificateUtil

java.lang.Object

com.ibm.as400.access.AS400CertificateUtil

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

AS400CertificateUserProfileUtil, AS400CertificateVldlUtil

public abstract class AS400CertificateUtil
extends java.lang.Object
implements java.io.Serializable

Provides the methods common to AS400CertificateVldlUtil and AS400CertificateUserProfileUtil. The following example demonstrates the use of AS400CertificateUtil, AS400CertificateVldlUtil, and AS400CertificateUserProfileUtil. It copies an arbitrary number of X.509 certificates from an IBM i user profile to an IBM i validation list (vldl) object. The user profile certificates are first placed into a user space and then added to the validation list:

      // Get certificates from the local system
    AS400 as400 = new AS400();

      // Local variables
    AS400Certificate   as400certificate;
    AS400Certificate[] certs;

    Vector  certVector = new Vector();
    byte[]  handle;
    int     numberCerts;
    String  userName;


    try
    {

    AS400CertificateUserProfileUtil usrprf =
       new AS400CertificateUserProfileUtil(as400, "/QSYS.LIB/MYNAME.USRPRF");

    AS400CertificateVldlUtil vldl =
       new AS400CertificateVldlUtil(as400, "/QSYS.LIB/MYLIB.LIB/TEST.VLDL");

    AS400CertificateAttribute[] certAttribute = new AS400CertificateAttribute[2];


      // Copy certificates that belong to both "US" and "myname".
    certAttribute[0] =
       new AS400CertificateAttribute(AS400CertificateAttribute.SUBJECT_COUNTRY, "US");

    certAttribute[1] =
       new AS400CertificateAttribute(AS400CertificateAttribute.SUBJECT_COMMON_NAME, "myname");


      // Copy matching certificates from the user profile to user space, MYSPACE.
    numberCerts = usrprf.listCertificates(certAttribute, "/QSYS.LIB/MYLIB.LIB/MYSPACE.USRSPC");

    System.out.println("Number of certificates found = " +  numberCerts);


      // Start reading certificates from the user space into AS400Certificate[].
      // All complete certificates in the 8 Kbyte buffer will be returned.
    certs = usrprf.getCertificates("/QSYS.LIB/MYLIB.LIB/MYSPACE.USRSPC", 0, 8);

       // Continue to read the entire user space using 8 Kbyte buffer
     while (null != certs)
     {
            // Gather certificates in a vector
          for (int i = 0; i < certs.length; ++i)
          {
            certVector.addElement(certs[i]);
          }

            certs = usrprf.getNextCertificates(8);
     }


      // Add all the certificates to validation list object
     for (int i = 0; i < certVector.size(); ++i)
     {
       as400certificate =  (AS400Certificate)certVector.elementAt(i);
       vldl.addCertificate(as400certificate.getEncoded());
     }
     // Delete first certificate added to vldl using its handle
     as400certificate =  (AS400Certificate)certVector.elementAt(0);
     handle = usrprf.getCertificateHandle(as400certificate.getEncoded());
     vldl.deleteCertificateByHandle(handle);
       // Delete 2nd certificate added to vldl using entire ASN.1 certificate
     as400certificate =  (AS400Certificate)certVector.elementAt(1);
     vldl.deleteCertificate(as400certificate.getEncoded());
       // Display user profile name associated with the 1st certificate
     userName = usrprf.findCertificateUserByHandle(handle);
     System.out.println("User profile name = " + userName);
    }
    catch (Exception e)
    {
        System.out.println(e.toString());
    }
  

See Also:

AS400CertificateVldlUtil, AS400CertificateUserProfileUtil, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_BUFFER_SIZE Recommended buffer size in kilobytes.
static int	MAX_BUFFER_SIZE Maximum buffer size in kilobytes.
static int	MIN_BUFFER_SIZE Minimum buffer size in kilobytes.

Constructor Summary

Constructors

Constructor and Description
AS400CertificateUtil() Constructs an AS400CertificateUtil object.
AS400CertificateUtil(AS400 system, java.lang.String path) Constructs an AS400CertificateUtil object.

Method Summary

Methods

Modifier and Type	Method and Description
void	addAS400CertificateListener(AS400CertificateListener listener) Adds an AS400Certificate listener to receive AS400Certificate events.
abstract void	addCertificate(byte[] certificate) Adds the certificate to the repository.
void	addPropertyChangeListener(java.beans.PropertyChangeListener l) Adds a property change listener.
void	addVetoableChangeListener(java.beans.VetoableChangeListener l) Adds the VetoableChangeListener.
abstract void	deleteCertificate(byte[] certificate) Deletes the certificate from the repository.
abstract void	deleteCertificateByHandle(byte[] certificatehandle) Deletes the certificate from the repository.
byte[]	getCertificateHandle(byte[] certificate) Returns the IBM i certificate handle which uniquely identifies this certificate.
AS400Certificate[]	getCertificates(java.lang.String userSpaceName, int firstCertificateToReturn, int buffSize) Retrieves the certificate placed in a user space by listCertificates.
AS400Certificate[]	getFirstCertificates(java.lang.String userSpaceName, int buffSize) Retrieves certificates placed in the user space by listCertificates starting at the first certificate in the user space.
java.lang.String	getName() Returns the name of the IBM i certificate repository.
AS400Certificate[]	getNextCertificates(int buffSize) Retrieves the next certificates placed in a user space by listCertificates.
java.lang.String	getObjectInfo() Returns free form object info.
java.lang.String	getPath() Returns the integrated file system path name of the IBM i certificate repository.
AS400	getSystem() Returns the system object.
abstract int	listCertificates(AS400CertificateAttribute[] certificateAttributes, java.lang.String userSpaceName) Returns certificates which match the specified attributes in the specified existing user space.
void	removeAS400CertificateListener(AS400CertificateListener l) Removes this listener.
void	removePropertyChangeListener(java.beans.PropertyChangeListener l) Removes this property change listener.
void	removeVetoableChangeListener(java.beans.VetoableChangeListener l) Removes this vetoable change listener.
void	setObjectInfo(java.lang.String information) Set free form object information
abstract void	setPath(java.lang.String path) Sets the path for the user space.
void	setSystem(AS400 system) Sets the system on which the certificate repository exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

Recommended buffer size in kilobytes. Used when returning certificates found during a get certificate operation.

See Also:

Constant Field Values

MAX_BUFFER_SIZE

public static final int MAX_BUFFER_SIZE

Maximum buffer size in kilobytes. Used when returning certificates found during a get certificate operation.

See Also:

Constant Field Values

MIN_BUFFER_SIZE

public static final int MIN_BUFFER_SIZE

Minimum buffer size in kilobytes. Used when returning certificates found during a get certificate operation.

See Also:

Constant Field Values

Constructor Detail

AS400CertificateUtil

public AS400CertificateUtil()

Constructs an AS400CertificateUtil object.

AS400CertificateUtil

public AS400CertificateUtil(AS400 system,
                    java.lang.String path)

Constructs an AS400CertificateUtil object.

Parameters:

system - The system on which the certificate repository exists.

path - The fully qualified integrated file system path name of the validation list or user profile. For example, /QSYS.LIB/MYLIB.LIB/MYVLDL.VLDL or /QSYS.LIB/MYPROFILE.USRPRF.

Method Detail

addCertificate

public abstract void addCertificate(byte[] certificate)
                             throws AS400SecurityException,
                                    ErrorCompletingRequestException,
                                    ExtendedIllegalArgumentException,
                                    ExtendedIOException,
                                    java.lang.InterruptedException,
                                    java.io.IOException,
                                    ObjectDoesNotExistException

Adds the certificate to the repository. Throws an ExtendedIOException if the certificate is already a member of the repository.

Parameters:

certificate - The ASN.1 Certificate to be added to the repository.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If invalid certificate.

ExtendedIOException - If certificate already added and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

addAS400CertificateListener

public void addAS400CertificateListener(AS400CertificateListener listener)

Adds an AS400Certificate listener to receive AS400Certificate events.

Parameters:

listener - The object listener.

See Also:

removeAS400CertificateListener(com.ibm.as400.access.AS400CertificateListener)

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener l)

Adds a property change listener. The specified property change listeners propertyChange method will be called each time the value of any bound property is changed. The property listener object is added to a list of property change listeners. It can be removed with the removePropertyChangeListener() method.

Parameters:

l - The property change listener.

See Also:

removePropertyChangeListener(java.beans.PropertyChangeListener)

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener l)

Adds the VetoableChangeListener. The specified VetoableChangeListeners vetoableChange method will be called each time the value of any constrained property is changed.

Parameters:

l - The VetoableChangeListener.

See Also:

removeVetoableChangeListener(java.beans.VetoableChangeListener)

deleteCertificate

public abstract void deleteCertificate(byte[] certificate)
                                throws AS400SecurityException,
                                       ErrorCompletingRequestException,
                                       ExtendedIllegalArgumentException,
                                       ExtendedIOException,
                                       java.lang.InterruptedException,
                                       java.io.IOException,
                                       ObjectDoesNotExistException

Deletes the certificate from the repository. Throws ExtendedIOException if the certificate is not present in the repository.

Parameters:

certificate - The ASN.1 Certificate to be deleted from the repository.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If invalid certificate.

ExtendedIOException - If certificate not found and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

deleteCertificateByHandle

public abstract void deleteCertificateByHandle(byte[] certificatehandle)
                                        throws AS400SecurityException,
                                               ErrorCompletingRequestException,
                                               ExtendedIllegalArgumentException,
                                               ExtendedIOException,
                                               java.lang.InterruptedException,
                                               java.io.IOException,
                                               ObjectDoesNotExistException

Deletes the certificate from the repository. Throws ExtendedIOException if the certificate is not present in the repository.

Parameters:

certificatehandle - The IBM i certificate handle of the certificate to be deleted from the repository.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If invalid certificate handle.

ExtendedIOException - If certificate not found and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

getCertificates

public AS400Certificate[] getCertificates(java.lang.String userSpaceName,
                                 int firstCertificateToReturn,
                                 int buffSize)
                                   throws AS400SecurityException,
                                          ErrorCompletingRequestException,
                                          ExtendedIllegalArgumentException,
                                          ExtendedIOException,
                                          java.lang.InterruptedException,
                                          java.io.IOException,
                                          ObjectDoesNotExistException

Retrieves the certificate placed in a user space by listCertificates. The certificates are not deleted from the user space. Returns certificates starting from firstCertificateToReturn(), inclusive. The first certificate in the user space is at location 0.

Parameters:

userSpaceName - The fully qualified integrated file system path name of the user space to get the certificates, for example, /QSYS.LIB/MYLIB.LIB/MYUSRSPC.USRSPC. The ten character AS4/00 library of the user space may also be specified as %CURLIB% or %LIBL%. See QSYSObjectPathName

firstCertificateToReturn - The first certificate in the user space to return. The first certificate in the user space is at location 0.

buffSize - The number of kilobytes allocated for the returned certificates. Increasing this value for remote invocations will require more client memory and longer transmission times. The recommended default buffer size is 128 kilobytes. The minimum buffer size allowed is 8 kilobytes.

Returns:

An array of AS400Certificates which fit in a buffer of size bufferSize.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If buffer size out of range or too small for one certificate, firstCertificateToReturn set to more than the total number of certificates in user space, and other invalid input parameters.

ExtendedIOException - If no certificate returned, user space certificates not stored in format "CERT0100", and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

getCertificateHandle

public byte[] getCertificateHandle(byte[] certificate)
                            throws AS400SecurityException,
                                   ErrorCompletingRequestException,
                                   ExtendedIOException,
                                   java.lang.InterruptedException,
                                   java.io.IOException,
                                   ObjectDoesNotExistException

Returns the IBM i certificate handle which uniquely identifies this certificate.

Parameters:

certificate - The ASN.1 Certificate used to generate the handle.

Returns:

The IBM i certificate handle.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIOException - If invalid certificate and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

getFirstCertificates

public AS400Certificate[] getFirstCertificates(java.lang.String userSpaceName,
                                      int buffSize)
                                        throws AS400SecurityException,
                                               ErrorCompletingRequestException,
                                               ExtendedIllegalArgumentException,
                                               ExtendedIOException,
                                               java.lang.InterruptedException,
                                               java.io.IOException,
                                               ObjectDoesNotExistException

Retrieves certificates placed in the user space by listCertificates starting at the first certificate in the user space.

Parameters:

userSpaceName - The fully qualified integrated file system path name of the user space to get the certificates, for example, /QSYS.LIB/MYLIB.LIB/MYUSRSPC.USRSPC. The ten character library of the user space may also be specified as %CURLIB% or %LIBL%. See QSYSObjectPathName

buffSize - The number of kilobytes allocated for the returned certificates. Increasing this value for remote invocations will require more client memory and longer transmission times. The recommended default buffer size is 128 kilobytes. The minimum buffer size allowed is 8 kilobytes.

Returns:

An array of AS400Certificates which fit in a buffer of size bufferSize.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If buffer size out of range or too small for one certificate and other invalid input parameters.

ExtendedIOException - If no certificate returned, user space certificates not stored in format "CERT0100", and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

getName

public java.lang.String getName()

Returns the name of the IBM i certificate repository.

Returns:

The IBM i object name. If the name has not been set, an empty string is returned.

getNextCertificates

public AS400Certificate[] getNextCertificates(int buffSize)
                                       throws AS400SecurityException,
                                              ErrorCompletingRequestException,
                                              ExtendedIllegalArgumentException,
                                              ExtendedIOException,
                                              java.lang.InterruptedException,
                                              java.io.IOException,
                                              ObjectDoesNotExistException

Retrieves the next certificates placed in a user space by listCertificates. getCertificates or getFirstCertificates must be invoked first to set the user space name and initial certificate to return or unpredicatable results will occur. Returns certificates starting from the last call to getNextCertificates.

Parameters:

buffSize - The number of kiloBytes allocated for the returned certificates. Increasing this value for remote invocations will require more client memory and longer transmission times. The minimum buffer size allowed is 8 kilobytes.

Returns:

An array of AS400Certificates which fit in a buffer of size bufferSize. Null is returned if all certificates have been successfully retrieved.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If buffer size out of range or too small for one certificate.

ExtendedIOException - If certificates are not in "CERT0100" format in the user space, user space and initial certificate to return are not set by calling getCertificates or getFirstCertificates, and other IBM i certificate access errors.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

See Also:

listCertificates(com.ibm.as400.access.AS400CertificateAttribute[], java.lang.String)

getObjectInfo

public java.lang.String getObjectInfo()

Returns free form object info.

Returns:

The free form string info.

getPath

public java.lang.String getPath()

Returns the integrated file system path name of the IBM i certificate repository.

Returns:

The fully qualified IBM i object name. If the name as not been set, an empty string is returned.

getSystem

public AS400 getSystem()

Returns the system object.

Returns:

The system object. If the system has not been set, null is returned.

listCertificates

public abstract int listCertificates(AS400CertificateAttribute[] certificateAttributes,
                   java.lang.String userSpaceName)
                              throws AS400SecurityException,
                                     ErrorCompletingRequestException,
                                     ExtendedIllegalArgumentException,
                                     ExtendedIOException,
                                     java.lang.InterruptedException,
                                     java.io.IOException,
                                     ObjectDoesNotExistException

Returns certificates which match the specified attributes in the specified existing user space. The underlying certificate repositories are not locked during the listCertificates operation. Certificates are stored into the user space with CERT0100 format. See the IBM i QsyListVldlCertificates (QSYLSTVC) and QsyListUserCertificates (QSYLSTUC) API's for further information.

Parameters:

certificateAttributes - The list of attributes the certificate must match. A value of null places all certificates from the repository into the user space. An empty String or empty byte array search attribute will search for certificates that do not have this attribute. For example, SUBJECT_ORGANIZATION = new String("") will search for certificates without the subject organization field. Null search attributes are ignored.

userSpaceName - The fully qualified integrated file system path name of the user space to put the list results, for example, /QSYS.LIB/MYLIB.LIB/MYUSRSPC.USRSPC. The ten character library of the user space may also be specified as %CURLIB% or %LIBL%. See QSYSObjectPathName

Returns:

The number of certificates found.

Throws:

AS400SecurityException - If a security or authority error occurs.

ErrorCompletingRequestException - If an error occurs before the request is completed.

ExtendedIllegalArgumentException - If invalid search attributes or input parameter.

ExtendedIOException - If IBM i certificate access error.

java.lang.InterruptedException - If this thread is interrupted.

java.io.IOException - If an error occurs while communicating with the system.

ObjectDoesNotExistException - If the IBM i object does not exist.

removeAS400CertificateListener

public void removeAS400CertificateListener(AS400CertificateListener l)

Removes this listener.

Parameters:

l - The AS400CertificateListener.

See Also:

addAS400CertificateListener(com.ibm.as400.access.AS400CertificateListener)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener l)

Removes this property change listener.

Parameters:

l - The property change listener.

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener l)

Removes this vetoable change listener.

Parameters:

l - The VetoableChangeListener.

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener)

setObjectInfo

public void setObjectInfo(java.lang.String information)

Set free form object information

Parameters:

information - The free form info.

setPath

public abstract void setPath(java.lang.String path)
                      throws java.beans.PropertyVetoException

Sets the path for the user space.

Parameters:

path - The fully qualified integrated file system path name.

Throws:

java.beans.PropertyVetoException - If the change is vetoed.

setSystem

public void setSystem(AS400 system)
               throws java.beans.PropertyVetoException

Sets the system on which the certificate repository exists.

Parameters:

system - The system on which the repository exists.

Throws:

java.beans.PropertyVetoException - If the change is vetoed.