Package COM.activesw.api.client.ssl

Interface AwSSL

All Known Implementing Classes:

AwSSLEntrust, AwSSLJSSE

public interface AwSSL

The Client API to the Broker Java API SSL library defined as an interface. This is really implemented by a class, one for Native and one for Plugin.

See Also:

AwSSLSocketInfo, AwSSLCertificate

Field Summary

Fields

Modifier and Type	Field	Description
static int	CLIENT_WANTS_CLEARTEXT_CONNECTION
static int	CLIENT_WANTS_CLIENT_AUTHENTICATED
static int	CLIENT_WANTS_SERVER_AUTHENTICATID

Method Summary

Modifier and Type	Method	Description
void	closeSocket(AwSSLSocketInfo socket)	Closes a previously created socket.
AwSSLSocketInfo	createClientSocket(AwSSLContext context, int secure, java.lang.String host, int port, int block, boolean encryption)	Creates a client socket with the specified properties.
AwSSLContext	createContext(java.lang.String keyfile, java.lang.String trustfile, java.lang.String keystoreType, java.lang.String truststoreType, java.lang.String cipherSuites, java.lang.String password)
AwSSLContext	createSSLContext(java.lang.String keyfile, java.lang.String password)	Creates and initializes an SSL context.
void	destroyContext(AwSSLContext context)	Destroys an SSL context.
AwSSLCertificate	getCertificate(AwSSLContext context)	Returns the certificate for the supplied Distinguished Name.
java.lang.String[]	getDnList(AwSSLContext context)	Returns the list of the Distinguished Names in the keyfile.
AwSSLCertificate	getOtherPartysCertificate(AwSSLSocketInfo socket)	Returns the certificate of the other party if the connection was authenticated.
java.lang.String[]	getTRList(AwSSLContext context)	Returns the list of the Distinguished Names of trusted roots in the keyfile.
boolean	isDnAvailable(AwSSLContext context, java.lang.String dn)	Returns whether or not a certificate for the supplied Distinguished Name is available in the keyfile.
boolean	isExportLibrary()	Returns whether this library uses U.S.
int	isMoreDataAvailable(AwSSLSocketInfo socket)	Returns the number of bytes that are readable from the socket.
boolean	modifyPassword(AwSSLContext context, java.lang.String newpassword)	Changes the password protecting the keyfile.
int	read(AwSSLSocketInfo socket, byte[] buffer, int offset, int bytesToRead)	Provided for Entrust Support
byte[]	read(AwSSLSocketInfo socket, int offset, int bytesToRead)	Reads a number of bytes from the socket and returns the array.
boolean	selectEncryptionDn(AwSSLContext context, java.lang.String dn)	Selects the key of for the supplied Distinguished Name as the key for encryption.
int	write(AwSSLSocketInfo socket, byte[] writebuf)	Writes the array of bytes to the socket and returns the number of bytes written.

Field Detail

CLIENT_WANTS_SERVER_AUTHENTICATID

static final int CLIENT_WANTS_SERVER_AUTHENTICATID

See Also:

Constant Field Values

CLIENT_WANTS_CLIENT_AUTHENTICATED

static final int CLIENT_WANTS_CLIENT_AUTHENTICATED

See Also:

Constant Field Values

CLIENT_WANTS_CLEARTEXT_CONNECTION

static final int CLIENT_WANTS_CLEARTEXT_CONNECTION

See Also:

Constant Field Values

Method Detail

createSSLContext

AwSSLContext createSSLContext(java.lang.String keyfile,
                              java.lang.String password)
                       throws java.lang.RuntimeException

Creates and initializes an SSL context. The returned context must be presented for all operations.

Parameters:

keyfile - The name of the file containing the secret keys.

password - The password for reading the keyfile.

Returns:

a context handle represented as a long.

Throws:

java.lang.RuntimeException - If an error occurs during initialization.

createContext

AwSSLContext createContext(java.lang.String keyfile,
                           java.lang.String trustfile,
                           java.lang.String keystoreType,
                           java.lang.String truststoreType,
                           java.lang.String cipherSuites,
                           java.lang.String password)
                    throws java.lang.RuntimeException

Throws:

java.lang.RuntimeException

destroyContext

void destroyContext(AwSSLContext context)

Destroys an SSL context. After destroying a context it is no longer valid.

Parameters:

context - A context handle to be destroyed.

isExportLibrary

boolean isExportLibrary()

Returns whether this library uses U.S. Domestic or exportable cipher strengths.

Returns:

true if the library is of export strength only.

modifyPassword

boolean modifyPassword(AwSSLContext context,
                       java.lang.String newpassword)
                throws java.lang.RuntimeException

Changes the password protecting the keyfile. Rewrites the keyfile using the new password.

Parameters:

context - A context handle.

newpassword - The new password for the keyfile.

Returns:

true if the update succeded.

Throws:

java.lang.RuntimeException - If an error occurs during the update.

getDnList

java.lang.String[] getDnList(AwSSLContext context)
                      throws java.lang.RuntimeException

Returns the list of the Distinguished Names in the keyfile.

Parameters:

context - A context handle.

Returns:

a list of strings each containing a Distinguished Name.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

getTRList

java.lang.String[] getTRList(AwSSLContext context)
                      throws java.lang.RuntimeException

Returns the list of the Distinguished Names of trusted roots in the keyfile.

Parameters:

context - A context handle.

Returns:

a list of strings each containing a Distinguished Name for a trusted root.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

getCertificate

AwSSLCertificate getCertificate(AwSSLContext context)
                         throws java.lang.RuntimeException

Returns the certificate for the supplied Distinguished Name.

Parameters:

context - A context handle.

Returns:

a reference to an AwSSLCertificate object if successful, or nil otherwise.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

See Also:

AwSSLCertificate

selectEncryptionDn

boolean selectEncryptionDn(AwSSLContext context,
                           java.lang.String dn)
                    throws java.lang.RuntimeException

Selects the key of for the supplied Distinguished Name as the key for encryption.

Parameters:

context - A context handle.

dn - The Distinguished Name whose key should be selected.

Returns:

true if the operation succeeded.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

isDnAvailable

boolean isDnAvailable(AwSSLContext context,
                      java.lang.String dn)
               throws java.lang.RuntimeException

Returns whether or not a certificate for the supplied Distinguished Name is available in the keyfile.

Parameters:

context - A context handle.

dn - The Distinguished Name to be inquired about.

Returns:

true if a certificate is available.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

createClientSocket

AwSSLSocketInfo createClientSocket(AwSSLContext context,
                                   int secure,
                                   java.lang.String host,
                                   int port,
                                   int block,
                                   boolean encryption)
                            throws java.lang.RuntimeException

Creates a client socket with the specified properties.

Parameters:

context - A context handle.

secure - The security properties of the socket (set to the selected CLIENT_* values above).

host - The name of the host to which the socket should connect.

port - The portnumber to which the socket should connect.

block - Set to 1 if the socket should be blocking, 0 for non-blocking.

Returns:

a reference to an AwSSLSocketInfo object if successful, or nil otherwise.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

See Also:

AwSSLSocketInfo

closeSocket

void closeSocket(AwSSLSocketInfo socket)
          throws java.lang.RuntimeException

Closes a previously created socket.

Parameters:

socket - The sockethandle returned in the AwSSLSocketInfo object.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

read

byte[] read(AwSSLSocketInfo socket,
            int offset,
            int bytesToRead)
     throws java.lang.RuntimeException

Reads a number of bytes from the socket and returns the array.

Parameters:

socket - The sockethandle returned in the AwSSLSocketInfo object.

bytesToRead - The number of bytes to read from the socket.

Returns:

an array of the bytes read from the socket if successful, or nil otherwise.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

read

int read(AwSSLSocketInfo socket,
         byte[] buffer,
         int offset,
         int bytesToRead)
  throws java.lang.RuntimeException

Provided for Entrust Support

Parameters:

socket - The sockethandle

buffer - The number of bytes to read from the socket.

offset - Offset from where to read

bytesToRead - Number of bytes to be read

Returns:

Number of bytes read.

Throws:

java.lang.RuntimeException

write

int write(AwSSLSocketInfo socket,
          byte[] writebuf)
   throws java.lang.RuntimeException

Writes the array of bytes to the socket and returns the number of bytes written.

Parameters:

socket - The sockethandle returned in the AwSSLSocketInfo object.

writebuf - The array of bytes to write to the socket.

Returns:

the number of bytes actually written to the socket.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

isMoreDataAvailable

int isMoreDataAvailable(AwSSLSocketInfo socket)
                 throws java.lang.RuntimeException

Returns the number of bytes that are readable from the socket.

Parameters:

socket - The sockethandle returned in the AwSSLSocketInfo object.

Returns:

the number of bytes readable from the socket.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.

getOtherPartysCertificate

AwSSLCertificate getOtherPartysCertificate(AwSSLSocketInfo socket)
                                    throws java.lang.RuntimeException

Returns the certificate of the other party if the connection was authenticated.

Parameters:

socket - The sockethandle returned in the AwSSLSocketInfo object.

Returns:

an object reference to an AwSSLCertificate object if successful, or nil otherwise.

Throws:

java.lang.RuntimeException - If an error occurs during the operation.