org.iids.aos.kernel
Class KernelImpl

java.lang.Object
  org.iids.aos.kernel.KernelImpl

All Implemented Interfaces:

AOSapi

public class KernelImpl
extends java.lang.Object
implements AOSapi

RPC-neutral implementation of the AOS kernel API. This implementation is called by RPC dispatchers to do their work. Methods are documented in AOSapi. Thread-safe.

Author:

Patrick Verkaik, Arno Bakker

Nested Class Summary

Nested classes/interfaces inherited from interface org.iids.aos.kernel.AOSapi

AOSapi.AcceptResult, AOSapi.ConnectResult, AOSapi.CreateRoleResult, AOSapi.PrepareWaitACResult, AOSapi.SecSuites, AOSapi.WaitACResult

Field Summary

protected byte[]	certificate The X509 public key certicate corresponding to privateKey in PEM format.
protected KernelConfig	config Kernel config
protected java.security.PrivateKey	privateKey The private key of the AOS kernel.
protected java.lang.String	scid The SCID of the AOS kernel.

Fields inherited from interface org.iids.aos.kernel.AOSapi

ACTP_TLS_PROTOCOL_VERSION, MUX_TLS_PROTOCOL_VERSION, SCID_AUTH_ALGO, SCID_AUTH_KEYSIZE, SCID_CERT_SIGN_ALGO, SCID_DIGEST_ALGO, SCID_DIGEST_ALGO_BITLENGTH, SEGMENT_CERT_SUBTYPE, SEGMENT_DIGEST_ALGO, SEGMENT_DIGEST_ALGO_BITLENGTH, SEGMENT_SIGN_SUBTYPE, SEGMENT_TOC_SUBTYPE, SIGN_TOC_ALGO, SIGN_TOC_CERTTYPE, XDR_ENCODING_CHARSET

Constructor Summary

KernelImpl(KernelConfig config)
Creates an AOS kernel object listening on the given TCP/IP contact points and maintaining file system state in the given directory.

Method Summary

AOSapi.AcceptResult	accept(Cookie cookie, int listenPort, boolean blocking) Returns the next permitted connection waiting at a listen endpoint.
void	closeConnection(Cookie cookie, int connectionID) Closes a connection.
void	closeListenEndpoint(Cookie cookie, int listenPort) Destroys a listen endpoint and closes any pending connections that have arrived at the listen endpoint.
AOSapi.ConnectResult	connect(Cookie cookie, Endpoint listenEndpoint, java.lang.String[] secSuites) Establishes a connection by connecting to a remote listen endpoint.
int	createAgentContainer(Cookie cookie) Creates an empty agent container.
void	createInitRole(Cookie cookie, boolean enable)
Endpoint	createListenEndpoint(Cookie cookie, int listenPort, java.lang.String[] secSuites) Creates a listen endpoint.
AOSapi.CreateRoleResult	createRole(Cookie cookie, RoleBitmap bitmap) Creates a new role.
int	createSegment(Cookie cookie, int acid, int segmentType, byte[] subtype, byte[] description) Creates a new empty segment and TOC entry in the given agent container, using the given parameters.
void	deleteAgentContainer(Cookie cookie, int acid) Deletes an agent container.
void	deleteRole(Cookie cookie, Cookie childCookie) Deletes an existing role and all kernel resources owned by that role (Agent containers, connection ports, listen ports, other roles etc.)
void	deleteSegment(Cookie cookie, int acid, int segID) Removes the given segment from the given agent container.
void	finalizeAgentContainer(Cookie cookie, int acid) Finalizes an agent container: (a) computes checksums of the container's segments and signs the container using the AOS kernel's private key, and (b) writes the TOC, signature and AOS kernel's key certificate to the agent container's finalization segments.
java.lang.String	getLocalScid()
int	getParam(Cookie cookie, java.lang.String parameterName) Returns the value of an AOS parameter, a positive integer
TIDRecord	isKnownTID(TransactionID tid) Used by AgentContainerTransfer to see if we know this TID at all.
void	makePersistent(Cookie cookie, int acid, int segID) Marks the given segment of the given agent container as persistent.
byte[]	peek(Cookie cookie, int connectionID, int max, boolean blocking) As receive() but leaves the data that was read in the connection.
AOSapi.PrepareWaitACResult	prepareWaitAgentContainer(Cookie cookie, java.lang.String[] secSuites) Prepares an incoming agent container shipment.
byte[]	readSegment(Cookie cookie, int acid, int segID, int offset, int length) Reads a number of bytes from the given segment in the given agent container.
TOCEntry[]	readTOC(Cookie cookie, int acid, int offset, int n) Reads n TOC entries of an agent container, starting at the entry for segment ID 'offset'.
byte[]	receive(Cookie cookie, int connectionID, int max, boolean blocking) Reads available data from a connection up to a specified maximum.
void	recover()
void	reenableRole(Cookie cookie) Used to reset the role so that it can be used again.
SelectSets	select(Cookie cookie, SelectSets sets, boolean blocking) Cf.
int	send(Cookie cookie, int connectionID, byte[] buffer) Writes data to a connection.
void	shipAgentContainer(Cookie cookie, int acid, Endpoint dest, java.lang.String[] secSuites, TransactionID tid) Ships a finalized agent container to a remote AOS kernel.
void	shutdown()
AOSapi.WaitACResult	waitAgentContainer(Cookie cookie, TransactionID[] tids, int blockTime) Waits for completion of an incoming agent container shipment with any of the given transaction ID.
int	writeSegment(Cookie cookie, int acid, int segID, int offset, byte[] frombuf) Writes a number of bytes to the given segment in the given agent container.

Methods inherited from class java.lang.Object

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

Field Detail

config

protected KernelConfig config

Kernel config

privateKey

protected final java.security.PrivateKey privateKey

The private key of the AOS kernel.

certificate

protected final byte[] certificate

The X509 public key certicate corresponding to privateKey in PEM format.

scid

protected final java.lang.String scid

The SCID of the AOS kernel.

Constructor Detail

KernelImpl

public KernelImpl(KernelConfig config)
           throws java.io.IOException,
                  java.security.KeyStoreException,
                  java.security.cert.CertificateException,
                  java.security.KeyManagementException,
                  java.security.NoSuchAlgorithmException,
                  java.security.UnrecoverableKeyException,
                  java.security.cert.CertificateEncodingException,
                  KernelException

Creates an AOS kernel object listening on the given TCP/IP contact points and maintaining file system state in the given directory.

Throws:

java.io.IOException

java.security.KeyStoreException

java.security.cert.CertificateException

java.security.KeyManagementException

java.security.NoSuchAlgorithmException

java.security.UnrecoverableKeyException

java.security.cert.CertificateEncodingException

KernelException

Method Detail

getLocalScid

public java.lang.String getLocalScid()

shutdown

public void shutdown()

recover

public void recover()
             throws KernelException

Throws:

KernelException

createRole

public AOSapi.CreateRoleResult createRole(Cookie cookie,
                                          RoleBitmap bitmap)
                                   throws KernelException

Description copied from interface: AOSapi

Creates a new role.

Specified by:

createRole in interface AOSapi

Parameters:

cookie - caller cookie

bitmap - the role bitmap for the new role

Returns:

a CreateRoleResult

Throws:

UnknownRoleException - if the caller is unknown

KernelException

See Also:

AOSapi.createRole(org.iids.aos.kernel.Cookie, org.iids.aos.kernel.RoleBitmap)

deleteRole

public void deleteRole(Cookie cookie,
                       Cookie childCookie)
                throws KernelException

Description copied from interface: AOSapi

Deletes an existing role and all kernel resources owned by that role (Agent containers, connection ports, listen ports, other roles etc.)

Specified by:

deleteRole in interface AOSapi

Parameters:

cookie - caller cookie, must correspond to the parent role that created this role

childCookie - cookie of the role to be deleted

Throws:

KernelException

See Also:

AOSapi.deleteRole(org.iids.aos.kernel.Cookie, org.iids.aos.kernel.Cookie)

createAgentContainer

public int createAgentContainer(Cookie cookie)
                         throws KernelException

Description copied from interface: AOSapi

Creates an empty agent container.

Specified by:

createAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

Returns:

the agent container ID

Throws:

KernelException

See Also:

AOSapi.createAgentContainer(org.iids.aos.kernel.Cookie)

deleteAgentContainer

public void deleteAgentContainer(Cookie cookie,
                                 int acid)
                          throws KernelException

Description copied from interface: AOSapi

Deletes an agent container.

Specified by:

deleteAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to delete

Throws:

KernelException

See Also:

AOSapi.deleteAgentContainer(org.iids.aos.kernel.Cookie, int)

createSegment

public int createSegment(Cookie cookie,
                         int acid,
                         int segmentType,
                         byte[] subtype,
                         byte[] description)
                  throws KernelException

Description copied from interface: AOSapi

Creates a new empty segment and TOC entry in the given agent container, using the given parameters. The created segment is marked transient.

Specified by:

createSegment in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to create a segment in

segmentType - see XDR documentation of TOC_ENTRY

subtype - see XDR documentation of TOC_ENTRY

description - see XDR documentation of TOC_ENTRY

Returns:

the segment ID

Throws:

KernelException

See Also:

AOSapi.createSegment(org.iids.aos.kernel.Cookie, int, int, byte[], byte[])

deleteSegment

public void deleteSegment(Cookie cookie,
                          int acid,
                          int segID)
                   throws KernelException

Description copied from interface: AOSapi

Removes the given segment from the given agent container.

Specified by:

deleteSegment in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to delete segment from

segID - segment to delete

Throws:

KernelException

See Also:

AOSapi.deleteSegment(org.iids.aos.kernel.Cookie, int, int)

readTOC

public TOCEntry[] readTOC(Cookie cookie,
                          int acid,
                          int offset,
                          int n)
                   throws KernelException

Description copied from interface: AOSapi

Reads n TOC entries of an agent container, starting at the entry for segment ID 'offset'. May return fewer than n entries iff fewer than n are available from that offset. Also note that the sequence of segment IDs in the agent container may contain gaps. Therefore, the segment IDs of returned entries may exceed 'n+offset-1'. The finalization TOC entries (see XDR specification) are available only if finalizeAgentContainer() has been called at some point. The migration TOC entries (see XDR specification) are available only if the agent container was originally shipped from another AOS kernel.

Specified by:

readTOC in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to read TOC from

offset - segment ID of first entry requested

n - the number of entries requested

Returns:

the TOC entries read (possibly empty)

Throws:

KernelException

See Also:

AOSapi.readTOC(org.iids.aos.kernel.Cookie, int, int, int)

readSegment

public byte[] readSegment(Cookie cookie,
                          int acid,
                          int segID,
                          int offset,
                          int length)
                   throws KernelException

Description copied from interface: AOSapi

Reads a number of bytes from the given segment in the given agent container. If length > 0 and data is available at offset, then reads at least one byte and at most length bytes starting at offset. If length == 0 or no data is available at offset (e.g. offset >= segment size), then zero bytes are read. Fewer bytes than were requested may be read even if more data is available. The only way the caller can tell from the results of readSegment() that the end of a segment has been reached is to request at least one byte and be returned zero bytes.

Specified by:

readSegment in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to read from

segID - segment to read from

offset - offset in segment to start reading at

length - number of bytes requested

Returns:

the bytes that were read (possibly empty)

Throws:

KernelException

See Also:

AOSapi.readSegment(org.iids.aos.kernel.Cookie, int, int, int, int)

writeSegment

public int writeSegment(Cookie cookie,
                        int acid,
                        int segID,
                        int offset,
                        byte[] frombuf)
                 throws KernelException

Description copied from interface: AOSapi

Writes a number of bytes to the given segment in the given agent container. If frombuf.length > 0, then writes at least one byte and at most frombuf.length bytes starting at offset. Otherwise does nothing. Fewer bytes may be written than were requested even if more data can be written in a subsequent call.

Specified by:

writeSegment in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to write to

segID - segment to write to

offset - offset in segment to start writing at

frombuf - buffer containing the bytes to write

Returns:

the number of bytes that were written

Throws:

KernelException

See Also:

AOSapi.writeSegment(org.iids.aos.kernel.Cookie, int, int, int, byte[])

makePersistent

public void makePersistent(Cookie cookie,
                           int acid,
                           int segID)
                    throws KernelException

Description copied from interface: AOSapi

Marks the given segment of the given agent container as persistent. Henceforth the segment cannot be deleted, modified, or made transient.

Specified by:

makePersistent in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container whose segment to make persistent

segID - segment to make persistent

Throws:

KernelException

See Also:

AOSapi.makePersistent(org.iids.aos.kernel.Cookie, int, int)

finalizeAgentContainer

public void finalizeAgentContainer(Cookie cookie,
                                   int acid)
                            throws KernelException

Description copied from interface: AOSapi

Finalizes an agent container: (a) computes checksums of the container's segments and signs the container using the AOS kernel's private key, and (b) writes the TOC, signature and AOS kernel's key certificate to the agent container's finalization segments.

Specified by:

finalizeAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to finalize

Throws:

KernelException

See Also:

AOSapi.finalizeAgentContainer(org.iids.aos.kernel.Cookie, int)

shipAgentContainer

public void shipAgentContainer(Cookie cookie,
                               int acid,
                               Endpoint dest,
                               java.lang.String[] secSuites,
                               TransactionID tid)
                        throws KernelException

Description copied from interface: AOSapi

Ships a finalized agent container to a remote AOS kernel.

Specified by:

shipAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

acid - agent container to ship

dest - the listen endpoint that the remote kernel uses for incoming agent container shipments (note: dest.port currently unused)

secSuites - a series of cipher suites acceptable to the caller, null or empty is equivalent to ALL_SEC_SUITES, as ACTP requires authentication.

tid - the transaction ID for this shipment, created by the remote AOS kernel

Throws:

KernelException

See Also:

AOSapi.shipAgentContainer(org.iids.aos.kernel.Cookie, int, org.iids.aos.kernel.Endpoint, java.lang.String[], org.iids.aos.kernel.TransactionID)

prepareWaitAgentContainer

public AOSapi.PrepareWaitACResult prepareWaitAgentContainer(Cookie cookie,
                                                            java.lang.String[] secSuites)
                                                     throws KernelException

Description copied from interface: AOSapi

Prepares an incoming agent container shipment. A transaction ID for this shipment is allocated and returned to the caller, together with this AOS kernel's virtual listen endpoint for incoming shipments. The caller should pass this information to its peer on the remote AOS kernel so that the peer may ship the agent container. The caller may then wait for completion of the shipment by calling waitAgentContainer().

Specified by:

prepareWaitAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

secSuites - a series of cipher suites acceptable to the caller, null or empty is equivalent to ALL_SEC_SUITES, as ACTP requires authentication.

Returns:

a transactionID and a listenEndpoint

Throws:

KernelException

See Also:

AOSapi.prepareWaitAgentContainer(org.iids.aos.kernel.Cookie, java.lang.String[])

isKnownTID

public TIDRecord isKnownTID(TransactionID tid)

Used by AgentContainerTransfer to see if we know this TID at all. Note that we have two types of query on the TID administration: 1. Getting the list of TIDs owned by a role 2. Checking if a TID is known at all, and if so, what its acceptable security suites are. Ideally, both queries should be equally fast. At present, the first is probably quicker.

waitAgentContainer

public AOSapi.WaitACResult waitAgentContainer(Cookie cookie,
                                              TransactionID[] tids,
                                              int blockTime)

Description copied from interface: AOSapi

Waits for completion of an incoming agent container shipment with any of the given transaction ID.

Specified by:

waitAgentContainer in interface AOSapi

Parameters:

cookie - caller cookie

tids - TransactionIDs for the AC shipment. All exceptions occuring will include the tid of the transaction that met the error.

blockTime - time in seconds in which the kernel will wait for an ACT to be initiated. blockTime 0 means ``poll''.

Returns:

the agent container ID of the incoming agent container, the tid and the source kernel, if the shipment was successful. The following exceptions can occur. Note, these exceptions are not thrown, but are encoded in the return value. # exception UnknownRoleException if the caller is unknown exception MethodNotAllowedException if the caller is not allowed to invoke the primitive exception ACTPACTooLargeException if the AC exceeds the remote kernel's internal limit exception ACTPACFormatException if the AC received did not meet the format exception ACTPACVerifyException if the AC received was not correctly signed exception InputOutputException if the kernel encountered persistent problems while receiving the AC exception TransientIOException if the kernel encountered transient problems while receiving the AC exception LimitExceededException if the caller exceeded an AOS resource limit exception KernelResetException if the kernel has been restarted exception IPCException if the operation failed due to an IPC error

See Also:

AOSapi.waitAgentContainer(org.iids.aos.kernel.Cookie, org.iids.aos.kernel.TransactionID[], int)

createListenEndpoint

public Endpoint createListenEndpoint(Cookie cookie,
                                     int listenPort,
                                     java.lang.String[] secSuites)
                              throws KernelException

Description copied from interface: AOSapi

Creates a listen endpoint. The listen port number can either be specified (explicit allocation) or left unspecified, in which case the AOS kernel will pick an unused listen port number. The caller may pass a series of cipher suites that it finds acceptable. This listen endpoint will only permit connections that use one of the specified cipher suites. If the caller does not pass a cipher suite, the listen endpoint will permit unsecure connections as well as connections that use any cipher suite supported by this AOS kernel. Note: other attributes of the listen endpoint, such as the number of outstanding connection requests that may be pending ('backlog'), are determined by the AOS kernel.

Specified by:

createListenEndpoint in interface AOSapi

Parameters:

cookie - caller cookie

listenPort - the listen port number to use, or 0 to let the AOS kernel pick one

secSuites - a series of cipher suites acceptable to the caller, or null or empty to leave unspecified. Kernel will then selected appropriate suites.

Returns:

the address of the listen endpoint created. The listen port number that identifies the listen endpoint is part of the address. The scid field of the address will be set iff this AOS kernel supports authentication

Throws:

KernelException

See Also:

AOSapi.createListenEndpoint(org.iids.aos.kernel.Cookie, int, java.lang.String[])

closeListenEndpoint

public void closeListenEndpoint(Cookie cookie,
                                int listenPort)
                         throws KernelException

Description copied from interface: AOSapi

Destroys a listen endpoint and closes any pending connections that have arrived at the listen endpoint.

Specified by:

closeListenEndpoint in interface AOSapi

Parameters:

cookie - caller cookie

listenPort - the listen port number

Throws:

KernelException

See Also:

AOSapi.closeListenEndpoint(org.iids.aos.kernel.Cookie, int)

accept

public AOSapi.AcceptResult accept(Cookie cookie,
                                  int listenPort,
                                  boolean blocking)
                           throws KernelException

Description copied from interface: AOSapi

Returns the next permitted connection waiting at a listen endpoint. If blocking, first waits until such a connection becomes available. Note that this call will only return connections that are permitted according to the secSuites specification of createListenEndpoint().

Specified by:

accept in interface AOSapi

Parameters:

cookie - caller cookie

listenPort - the listen port number

blocking - whether to allow this method to block

Returns:

the connection info or null if ! blocking and no permitted connection was available

Throws:

KernelException

See Also:

AOSapi.accept(org.iids.aos.kernel.Cookie, int, boolean)

connect

public AOSapi.ConnectResult connect(Cookie cookie,
                                    Endpoint listenEndpoint,
                                    java.lang.String[] secSuites)
                             throws KernelException

Description copied from interface: AOSapi

Establishes a connection by connecting to a remote listen endpoint. If the scid field of the listen endpoint address is set, then the remote AOS kernel must be authenticated in order for the connection establishment to succeed. The caller may pass a series of cipher suites that it finds acceptable for this connection, in which case the connection may only use one of the provided cipher suites. If the caller does not pass a cipher suite, the connection may be unsecure or may use any cipher suite supported by this AOS kernel.

Specified by:

connect in interface AOSapi

Parameters:

cookie - caller cookie

listenEndpoint - the address of the remote listen endpoint

secSuites - a series of cipher suites acceptable to the caller, or null or empty to leave unspecified

Returns:

the connection info

Throws:

KernelException

See Also:

AOSapi.connect(org.iids.aos.kernel.Cookie, org.iids.aos.kernel.Endpoint, java.lang.String[])

closeConnection

public void closeConnection(Cookie cookie,
                            int connectionID)
                     throws KernelException

Description copied from interface: AOSapi

Closes a connection. Pending unsent data will still be delivered (barring failures) as long as the remote party does not close as well. send() and receive() calls on the connection are illegal following this call.

Specified by:

closeConnection in interface AOSapi

Parameters:

cookie - caller cookie

connectionID - the connection to close

Throws:

KernelException

See Also:

AOSapi.closeConnection(org.iids.aos.kernel.Cookie, int)

send

public int send(Cookie cookie,
                int connectionID,
                byte[] buffer)
         throws KernelException

Description copied from interface: AOSapi

Writes data to a connection.

Specified by:

send in interface AOSapi

Parameters:

cookie - caller cookie

connectionID - the connection to write to

buffer - the buffer that holds the data

Returns:

the number of bytes actually written

Throws:

KernelException

See Also:

AOSapi.send(org.iids.aos.kernel.Cookie, int, byte[])

receive

public byte[] receive(Cookie cookie,
                      int connectionID,
                      int max,
                      boolean blocking)
               throws KernelException

Description copied from interface: AOSapi

Reads available data from a connection up to a specified maximum. If 'blocking', first blocks until at least one byte of data is available.

Specified by:

receive in interface AOSapi

Parameters:

cookie - caller cookie

connectionID - the connection to read

max - maximum number of bytes to read

blocking - whether to allow this method to block

Returns:

the bytes read. Non-empty if blocking

Throws:

KernelException

See Also:

AOSapi.receive(org.iids.aos.kernel.Cookie, int, int, boolean)

peek

public byte[] peek(Cookie cookie,
                   int connectionID,
                   int max,
                   boolean blocking)
            throws KernelException

Description copied from interface: AOSapi

As receive() but leaves the data that was read in the connection. The data remains available for reading by subsequent invocations to receive() and peek().

Specified by:

peek in interface AOSapi

Throws:

KernelException

See Also:

AOSapi.peek(org.iids.aos.kernel.Cookie, int, int, boolean)

select

public SelectSets select(Cookie cookie,
                         SelectSets sets,
                         boolean blocking)
                  throws KernelException

Description copied from interface: AOSapi

Cf. the UNIX select system call.

Specified by:

select in interface AOSapi

Parameters:

cookie - caller cookie

sets - set of three sets: readSet, writeSet, exceptSet readSet : set of local descriptors to check for data/connection availability writeSet set of local descriptors to check for writability exceptSet set of local descriptors to check for exceptions

blocking - whether to block or not

Returns:

All the sets will have been modified to reflect active descriptors.

Throws:

KernelException

getParam

public int getParam(Cookie cookie,
                    java.lang.String parameterName)
             throws KernelException

Description copied from interface: AOSapi

Returns the value of an AOS parameter, a positive integer

Specified by:

getParam in interface AOSapi

Parameters:

cookie - caller cookie

parameterName - the name of the AOS parameter

Returns:

the value of the parameter

Throws:

KernelException

reenableRole

public void reenableRole(Cookie cookie)
                  throws KernelException

Description copied from interface: AOSapi

Used to reset the role so that it can be used again. After a crash (or graceful exit where roles are not deleted) of AOS, all roles of AOS are locked and method invocations by a role throw a KernelResetException.

Specified by:

reenableRole in interface AOSapi

Parameters:

cookie - caller cookie

Throws:

KernelException

createInitRole

public void createInitRole(Cookie cookie,
                           boolean enable)
                    throws KernelException

Throws:

KernelException