ManagerTransportWithSMProxy ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- com.entrust.toolkit.util.ManagerTransport
- - com.entrust.toolkit.util.ManagerTransportWithSMProxy

All Implemented Interfaces:

PollableResource
```
public class ManagerTransportWithSMProxy
extends ManagerTransport
```
This class provides proxy order functionality for ManagerTransport connections.
SMProxyManagerTransport and ManagerTransport objects are created from the parameters supplied in the entrust.ini file. The following ProxyOrder values are used to control the Proxy Ordering:
- PROXYFIRST: a connection the proxy server will be attempted first. If that fails, a connection to the authority server will be attempted.
- PROXYLAST: a connection to the authority server will be attempted first. If that fails, a connection to the proxy server will be attempted. This is the default setting.
- NEVERPROXY: a connection to the authority server will be attempted. If that fails, a failure will occur
- ALWAYSPROXY: a connection to the proxy server will be attempted. If that fails, a failure will occur
The currently active ManagerTransport connection is determined in the call to isAvailable. This manager transport connection will continue to be used until another call is made to isAvailable.

NOTE: A simple TCP/IP connection attempt is used as a connectivity test. For the proxied connection, this test is performed against the proxy server, not the Security Manager.
Since:

8.1

Field Summary
- Fields inherited from class com.entrust.toolkit.util.ManagerTransport
  DEFAULT_CONNECT_TIMEOUT, DEFAULT_SO_LINGER, DEFAULT_SO_TIMEOUT, in, out, recipientAddress

Constructor Summary

Constructors
Constructor and Description
`ManagerTransportWithSMProxy(IniFile iniFile, ProxyOrder proxyOrder)` Constructor that takes an entrust.ini file and sets the proxy order.
`ManagerTransportWithSMProxy(java.lang.String entrustIniFile, ProxyOrder proxyOrder)` Constructor that takes an entrust.ini file path and sets the proxy order.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`beginNewSession()` Called whenever a new session or request to the PKI RA is about to be made.
`ResourceEvent`	`checkStatus(Resource resource)` This method checks if the CA services provided by the ManagerTransport object are available.
`void`	`dataReady(byte[] data)` Passes messages as a byte array.
`void`	`endSession()` Must be called whenever a session to the PKI RA is complete.
`java.lang.String`	`getAddress()` Returns the PKI RA's address specified by `managerIP` in other methods if it has not been explicitly defined.
`java.security.cert.X509Certificate[]`	`getClientCredentials()` Returns the client X509Certificate chain set by the object that implements this interface.
`GeneralMessageInfo`	`getGeneralMessageInfo(SecureStringBuffer refNum, AuthorizationCode authCode)` This is a convenience method used to retrieve information about a User that has not yet been created.
`java.io.InputStream`	`getInputStream()` Returns the input stream to read information from the PKI RA.
`java.io.OutputStream`	`getOutputStream()` Returns the output stream to write information to the PKI RA.
`int`	`getPort()` Returns the PKI RA's port
`int`	`getSoConnectTimeout()` Returns the setting for the connection timeout property of the underlying socket, in milliseconds, for socket based transports.
`int`	`getSoLinger()` Returns the setting for the SO_LINGER property of the underlying socket, in seconds, for socket based transports.
`int`	`getSoTimeout()` Returns the setting for the SO_TIMEOUT property of the underlying socket, in milliseconds, for socket based transports.
`java.security.cert.X509Certificate[]`	`getTrustRoots()` Returns the roots of trust that were set in this object, or null if no roots of trust were set.
`boolean`	`isAvailable()` Determines whether or not the PKI Registration Authority is available.
`ResourceMonitor`	`periodicPoll(int seconds, ResourceEventHandler handler, int trigger)` A convienance method that sets up the ManagerTransport object for polling to ensure PKI service availability.
`void`	`readNegPollRep()` Reads a 'negPollRep' TCP-based PKI message from the underlying transport.
`byte[]`	`readPKIX4Response(boolean getResponse)` Deprecated.
`byte[]`	`readPKIXCMPResponse(boolean getResponse)` This method reads a PKIXCMP message with a TCP stream header.
`void`	`setClientCredentials(java.security.cert.X509Certificate[] chain, java.security.PrivateKey signingKey)` Set client credentials for authenticating to a server.
`void`	`setClientCredentials(java.security.cert.X509Certificate verificationCertificate, java.security.cert.X509Certificate caCertificate, java.security.PrivateKey signingKey)` Deprecated.
`void`	`setSMProxyConfig(SMProxyConfig config)` Sets the SSL configuration for the proxied connection NOTE: if the proxy settings in the entrust.ini are missing or invalid, this method
`void`	`setSoConnectTimeout(int timeout)` Sets the Connection Timeout property of the underlying socket, with the specified timeout in milliseconds, for socket based transports.
`void`	`setSoLinger(boolean on, int linger)` Enables/Disables the SO_LINGER property of the underlying socket, with the specified linger time in seconds, for socket based transports.
`void`	`setSoTimeout(int timeout)` Sets the SO_TIMEOUT property of the underlying socket, with the specified timeout in milliseconds, for socket based transports.
`void`	`setStreams(java.io.InputStream input, java.io.OutputStream output, java.lang.String managerIP)` Sets the streams for communication to and from the PKI RA.
`void`	`setTrustRoots(java.security.cert.X509Certificate[] roots, LdapDirectory directory, ClientSettings cs)` Sets the TrustRoots used for SSL Authentication.

Methods inherited from class com.entrust.toolkit.util.ManagerTransport
calculateASNLength, DNSLookup, getInstance, getInstance, readManagerTransportMessage

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ManagerTransportWithSMProxy
```
public ManagerTransportWithSMProxy(java.lang.String entrustIniFile,
                           ProxyOrder proxyOrder)
                            throws java.io.FileNotFoundException,
                                   java.lang.Exception
```
    Constructor that takes an entrust.ini file path and sets the proxy order. The proxyFirst parameter is used to control which connection is attempted first.
    
    Parameters:
    entrustIniFile - the entrust.ini file path
    proxyOrder - the proxy order
    
    Throws:
    
    java.io.FileNotFoundException - if the entrust.ini file cannot be found
    
    java.lang.Exception - if any of the configuration parameters are invalid
  - ManagerTransportWithSMProxy
```
public ManagerTransportWithSMProxy(IniFile iniFile,
                           ProxyOrder proxyOrder)
                            throws java.lang.Exception
```
    Constructor that takes an entrust.ini file and sets the proxy order. The proxyFirst parameter is used to control which connection is attempted first.
    
    Parameters:
    entrustIniFile - the entrust.ini file path
    proxyOrder - the proxy order
    
    Throws:
    
    java.lang.Exception - if any of the configuration parameters are invalid
- Method Detail
  - checkStatus
```
public ResourceEvent checkStatus(Resource resource)
```
    Description copied from class: ManagerTransport
    
    This method checks if the CA services provided by the ManagerTransport object are available. To do this, this method sends an Event Server Status Request (ESSR) to request the event certificate. If the request is received and is a general PKIX message, then this is confirmation that the PKI service is available
    
    Specified by:
    
    checkStatus in interface PollableResource
    
    Overrides:
    
    checkStatus in class ManagerTransport
    
    Returns:
    the status of the ManagerTransport as a ResourceEvent
    See Also:
    ResourceEvent, Resource
  - periodicPoll
```
public ResourceMonitor periodicPoll(int seconds,
                           ResourceEventHandler handler,
                           int trigger)
```
    Description copied from class: ManagerTransport
    A convienance method that sets up the ManagerTransport object for polling to ensure PKI service availability. This method will return a ResourceMonitor object which can be used to monitor the ManagerTransport. If a ResourceEventHandler is specified, it will be used to handle events for this ManagerTransport. The ResourceEvent trigger threshold value must also be specified as one of the following:
    - OKAY (0) - Resource is operating normally
    - WARNING (100) - There may be a problem with the resource
    - BUSY (200) - The resource is busy, and cannot respond
    - FAILURE (300) - Some type of failure occured
    If ResourceEventHandler is null then the default ResourceOutputHandler which simply outputs events using the System.out will be used. The ResourceEventHandler will be added using the ResourceEventProcessor.setEventHandler(ResourceEventHandler) method.
    If the ResourceEvent trigger value is less than 0, then the default value of OKAY (0) will be used.
    Overrides:
    
    periodicPoll in class ManagerTransport
    
    Parameters:
    seconds - the length of time between each poll
    handler - a ResourceEventHandler used when this Resource is notified of an event
    trigger - Sets the level at which event notification is triggered by the HeartbeatEvent
    
    Returns:
    A ResourceMonitor which can be used to monitor this ManagerTransport object
    See Also:
    Resource, ResourceEvent, HttpManagerClient, HttpsManagerClient
  - setStreams
```
public void setStreams(java.io.InputStream input,
              java.io.OutputStream output,
              java.lang.String managerIP)
```
    Description copied from class: ManagerTransport
    
    Sets the streams for communication to and from the PKI RA.
    
    Overrides:
    
    setStreams in class ManagerTransport
    
    Parameters:
    input - the input stream to read information from the RA
    output - the output stream to write information to the RA
    managerIP - the PKI RA's IP address
  - getAddress
```
public java.lang.String getAddress()
```
    Description copied from class: ManagerTransport
    
    Returns the PKI RA's address specified by managerIP in other methods if it has not been explicitly defined.
    
    Overrides:
    
    getAddress in class ManagerTransport
    
    Returns:
    The recipient address (For example, www.acme.com, pkix@acme.com)
  - getPort
```
public int getPort()
```
    Description copied from class: ManagerTransport
    
    Returns the PKI RA's port
    
    Overrides:
    
    getPort in class ManagerTransport
    
    Returns:
    The port used to connect to the PKI
  - getOutputStream
```
public java.io.OutputStream getOutputStream()
```
    Description copied from class: ManagerTransport
    
    Returns the output stream to write information to the PKI RA.
    
    Overrides:
    
    getOutputStream in class ManagerTransport
    
    Returns:
    The RA output stream.
  - getInputStream
```
public java.io.InputStream getInputStream()
```
    Description copied from class: ManagerTransport
    
    Returns the input stream to read information from the PKI RA.
    
    Overrides:
    
    getInputStream in class ManagerTransport
    
    Returns:
    The RA input stream.
  - beginNewSession
```
public void beginNewSession()
```
    Description copied from class: ManagerTransport
    
    Called whenever a new session or request to the PKI RA is about to be made.
    beginNewSession() closes the existing socket connection, if there is one, and connects to the PKI RA again to prepare for the communication request.
    
    If a sub-class of ManagerTransport is created, override this method and the dataReady() method. Reset the connection to the RA.
    
    Overrides:
    
    beginNewSession in class ManagerTransport
  - endSession
```
public void endSession()
```
    Description copied from class: ManagerTransport
    
    Must be called whenever a session to the PKI RA is complete.
    endSession() closes the existing socket connection.
    
    If a sub-class of ManagerTransport is created, override this method and the dataReady() method. Reset the connection to the RA.
    
    Overrides:
    
    endSession in class ManagerTransport
  - dataReady
```
public void dataReady(byte[] data)
               throws java.io.IOException
```
    Description copied from class: ManagerTransport
    Passes messages as a byte array.
    dataReady(byte[] data) is called when a data message is ready for the PKI RA. Sub-classes of ManagerTransport can overide this method and send the data using any method they choose, e-mail or HTTP, for example. The sub-classes must first have implemented a simliar proxy mechanism on the PKI RA's side of the connection.
    
    A User object composes a message for the PKI RA and calls this method, passing the message in a byte array. Usually, a sub-class of ManagerTransport implements the dataReady() method and sends the message to the PKI RA. User then calls the readPKIXCMPResponse() method and expects to receive a byte array containing the RA's response.
    
    For example, this code fragment illustrates User using ManagerTransport:
```
      transport.dataReady(messageForManager);
      byte[] messageFromManager = transport.read();
  
```
    Overrides:
    
    dataReady in class ManagerTransport
    
    Parameters:
    data - the data that is ready to be sent to the RA
    
    Throws:
    
    java.io.IOException - thrown if the output stream has been closed before this method is called
    See Also:
    ManagerTransport.beginNewSession()
  - readPKIX4Response
```
@Deprecated
public byte[] readPKIX4Response(boolean getResponse)
                         throws java.security.GeneralSecurityException
```
    Deprecated.
    
    Description copied from class: ManagerTransport
    
    This method always throws an exception as the proto-PKIX protocol is no longer supported in the Toolkit.
    
    Overrides:
    
    readPKIX4Response in class ManagerTransport
    
    Returns:
    This method always throws a GeneralSecurityException
    
    Throws:
    
    java.security.GeneralSecurityException - always
  - setClientCredentials
```
@Deprecated
public void setClientCredentials(java.security.cert.X509Certificate verificationCertificate,
                                   java.security.cert.X509Certificate caCertificate,
                                   java.security.PrivateKey signingKey)
```
    Deprecated.
    
    Description copied from class: ManagerTransport
    
    Set client credentials for authenticating to a server. This implementation does nothing; it is intended to be overridden by subclasses that need to provide additional authentication, such as for SSL client authentication.
    
    Overrides:
    
    setClientCredentials in class ManagerTransport
  - setClientCredentials
```
public void setClientCredentials(java.security.cert.X509Certificate[] chain,
                        java.security.PrivateKey signingKey)
```
    Description copied from class: ManagerTransport
    
    Set client credentials for authenticating to a server. This implementation does nothing; it is intended to be overridden by subclasses that need to provide additional authentication, such as for SSL client authentication.
    
    Overrides:
    
    setClientCredentials in class ManagerTransport
  - setTrustRoots
```
public void setTrustRoots(java.security.cert.X509Certificate[] roots,
                 LdapDirectory directory,
                 ClientSettings cs)
                   throws java.security.cert.CertificateException,
                          CertificationRootException
```
    Description copied from class: ManagerTransport
    
    Sets the TrustRoots used for SSL Authentication. This implementation does nothing; it is intended to be overridden by subclasses that need to provide additional authentication, such as for SSL client authentication.
    
    Overrides:
    
    setTrustRoots in class ManagerTransport
    
    Throws:
    
    java.security.cert.CertificateException
    
    CertificationRootException
  - getClientCredentials
```
public java.security.cert.X509Certificate[] getClientCredentials()
```
    Description copied from class: ManagerTransport
    
    Returns the client X509Certificate chain set by the object that implements this interface. This method always returns null in this class because it will never be used.
    
    Overrides:
    
    getClientCredentials in class ManagerTransport
    
    Returns:
    the client X509Certificate chain set by the object that implements this interface
  - getTrustRoots
```
public java.security.cert.X509Certificate[] getTrustRoots()
```
    Description copied from class: ManagerTransport
    
    Returns the roots of trust that were set in this object, or null if no roots of trust were set. This method always returns null in this class because it will never be used.
    
    Overrides:
    
    getTrustRoots in class ManagerTransport
    
    Returns:
    the roots of trust that were set in this object, or null if no roots of trust were set.
  - getGeneralMessageInfo
```
public GeneralMessageInfo getGeneralMessageInfo(SecureStringBuffer refNum,
                                       AuthorizationCode authCode)
                                         throws EntrustPKIXCMPException
```
    Description copied from class: ManagerTransport
    This is a convenience method used to retrieve information about a User that has not yet been created. This method simply makes a call to PKIXCMPUtils.getGeneralMessageInfo(SecureStringBuffer, AuthorizationCode)
    For example:
```
 ManagerTransport man = new ManagerTransport("myPkI",829);
 GeneralMessageInfo info = man.getGeneralMessageInfo(refNum, authCode);
 ClientSettings settings = info.getClientSettings();  
 
```
    Overrides:
    
    getGeneralMessageInfo in class ManagerTransport
    
    Parameters:
    refNum - The reference number
    authCode - The Authorization code
    
    Returns:
    The GeneralMessageInfo object that encapsulated PKIX GeneralMessage Information
    
    Throws:
    
    EntrustPKIXCMPException
  - isAvailable
```
public boolean isAvailable()
```
    Description copied from class: ManagerTransport
    
    Determines whether or not the PKI Registration Authority is available.
    Contacts the PKIX-CMP service of the PKI Registration Authority checking the availability of this service, including its ability to process PKIX-CMP traffic.
    
    Overrides:
    
    isAvailable in class ManagerTransport
    
    Returns:
    true if the PKI Registration Authority is available; false otherwise
  - getSoLinger
```
public int getSoLinger()
```
    Description copied from class: ManagerTransport
    
    Returns the setting for the SO_LINGER property of the underlying socket, in seconds, for socket based transports.
    This property specifies the number of seconds to linger after the socket is closed. A value greater than zero indicates that when a call to ManagerTransport.endSession() is made, the underlying socket should wait up to the specified number of seconds for any data on the socket to be written before it is actually closed. A value of zero indicates that the socket should be closed immediately (but gracefully, without data loss). A value of -1 indicates that this property is disabled.
    
    By default the SO_LINGER property is enabled with a value of DEFAULT_SO_LINGER.
    
    Overrides:
    
    getSoLinger in class ManagerTransport
    
    Returns:
    the value of SO_LINGER in seconds
  - getSoTimeout
```
public int getSoTimeout()
```
    Description copied from class: ManagerTransport
    
    Returns the setting for the SO_TIMEOUT property of the underlying socket, in milliseconds, for socket based transports.
    This property specifies the number of milliseconds until a blocking operation fails and the control returns an error. A value of zero indicates that the blocking operation should wait indefinitely. A blocking operation can occur when a read operation is done on the InputStream associated with the underlying socket.
    
    By default the SO_TIMEOUT property is enabled with a value of DEFAULT_SO_TIMEOUT.
    
    Overrides:
    
    getSoTimeout in class ManagerTransport
    
    Returns:
    the value of SO_TIMEOUT in milliseconds
  - getSoConnectTimeout
```
public int getSoConnectTimeout()
```
    Description copied from class: ManagerTransport
    
    Returns the setting for the connection timeout property of the underlying socket, in milliseconds, for socket based transports.
    This property specifies the number of milliseconds until a blocking operation fails and the control returns an error. A value of zero indicates that the blocking operation should wait indefinitely. A blocking operation can occur when a connection attempt is made on the InputStream associated with the underlying socket.
    
    By default the connection timeout property is enabled with a value of DEFAULT_CONNECT_TIMEOUT.
    
    Overrides:
    
    getSoConnectTimeout in class ManagerTransport
    
    Returns:
    the value of connection timeout in milliseconds
  - setSoLinger
```
public void setSoLinger(boolean on,
               int linger)
                 throws java.lang.IllegalArgumentException
```
    Description copied from class: ManagerTransport
    
    Enables/Disables the SO_LINGER property of the underlying socket, with the specified linger time in seconds, for socket based transports.
    This property specifies the number of seconds to linger after the socket is closed. A a value greater than zero indicates that when a call to ManagerTransport.endSession() is made, the underlying socket should wait up to the specified number of seconds for any data on the socket to be written before it is actually closed. A value of zero indicates that the socket should be closed immediately (but gracefully, without data loss).
    
    By default the SO_LINGER property is enabled with a value of DEFAULT_SO_LINGER.
    
    Overrides:
    
    setSoLinger in class ManagerTransport
    
    Parameters:
    on - whether or not the SO_LINGER property is enabled
    linger - how long to linger for in seconds, if on is true
    
    Throws:
    
    java.lang.IllegalArgumentException - if the linger value is negative
  - setSoTimeout
```
public void setSoTimeout(int timeout)
                  throws java.lang.IllegalArgumentException
```
    Description copied from class: ManagerTransport
    
    Sets the SO_TIMEOUT property of the underlying socket, with the specified timeout in milliseconds, for socket based transports.
    This property specifies the number of milliseconds until a blocking operation fails and the control returns an error. A value of zero indicates that the blocking operation should wait indefinitely. A blocking operation can occur when a read operation is done on the InputStream associated with the underlying socket.
    
    By default the SO_TIMEOUT property is enabled with a value of DEFAULT_SO_LINGER.
    
    Overrides:
    
    setSoTimeout in class ManagerTransport
    
    Parameters:
    timeout - the specified timeout in milliseconds
    
    Throws:
    
    java.lang.IllegalArgumentException - if the timout is negative
  - setSoConnectTimeout
```
public void setSoConnectTimeout(int timeout)
                         throws java.lang.IllegalArgumentException
```
    Description copied from class: ManagerTransport
    
    Sets the Connection Timeout property of the underlying socket, with the specified timeout in milliseconds, for socket based transports.
    This property specifies the number of milliseconds until a blocking operation fails and the control returns an error. A value of zero indicates that the blocking operation should wait indefinitely. A blocking operation can occur when a connection is done on the InputStream associated with the underlying socket.
    
    By default the connection timeout property is enabled with a value of DEFAULT_CONNECT_TIMEOUT.
    
    Overrides:
    
    setSoConnectTimeout in class ManagerTransport
    
    Parameters:
    timeout - the specified timeout in milliseconds
    
    Throws:
    
    java.lang.IllegalArgumentException - if the timout is negative
  - readPKIXCMPResponse
```
public byte[] readPKIXCMPResponse(boolean getResponse)
                           throws java.io.IOException,
                                  java.security.GeneralSecurityException
```
    Description copied from class: ManagerTransport
    
    This method reads a PKIXCMP message with a TCP stream header.
    
    Overrides:
    
    readPKIXCMPResponse in class ManagerTransport
    
    Returns:
    the raw PKIX CMP message
    
    Throws:
    
    java.io.IOException
    
    java.security.GeneralSecurityException
  - readNegPollRep
```
public void readNegPollRep()
                    throws java.io.IOException
```
    Description copied from class: ManagerTransport
    
    Reads a 'negPollRep' TCP-based PKI message from the underlying transport.
    A 'negPollRep' is returned by the responder after a 'pkiMsg' containing PKIX-CMP confirmation message has been transported from initiator to responder. Receiving a 'negPollRep' indicates that the transaction has been successfully completed.
    
    Overrides:
    
    readNegPollRep in class ManagerTransport
    
    Throws:
    
    java.io.IOException - if an error occurs while reading the 'negPollRep' (i.e. unexpected end of data, incorrect message flag, invalid message length...)
  - setSMProxyConfig
```
public void setSMProxyConfig(SMProxyConfig config)
                      throws SMProxyException
```
    Sets the SSL configuration for the proxied connection NOTE: if the proxy settings in the entrust.ini are missing or invalid, this method
    
    Parameters:
    config - the configuration to set
    
    Throws:
    
    SMProxyException

Class ManagerTransportWithSMProxy

Field Summary

Fields inherited from class com.entrust.toolkit.util.ManagerTransport

Constructor Summary

Method Summary

Methods inherited from class com.entrust.toolkit.util.ManagerTransport

Methods inherited from class java.lang.Object

Constructor Detail

ManagerTransportWithSMProxy

ManagerTransportWithSMProxy

Method Detail

checkStatus

periodicPoll

setStreams

getAddress

getPort

getOutputStream

getInputStream

beginNewSession

endSession

dataReady

readPKIX4Response

setClientCredentials

setClientCredentials

setTrustRoots

getClientCredentials

getTrustRoots

getGeneralMessageInfo

isAvailable

getSoLinger

getSoTimeout

getSoConnectTimeout

setSoLinger

setSoTimeout

setSoConnectTimeout

readPKIXCMPResponse

readNegPollRep

setSMProxyConfig