001: /*
002: * <copyright>
003: *
004: * Copyright 2002-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.core.service;
028:
029: import java.io.IOException;
030: import java.io.InputStream;
031: import java.io.OutputStream;
032: import java.security.GeneralSecurityException;
033:
034: import org.cougaar.core.component.Service;
035: import org.cougaar.core.mts.MessageAddress;
036: import org.cougaar.core.mts.MessageAttributes;
037: import org.cougaar.core.mts.ProtectedInputStream;
038: import org.cougaar.core.mts.ProtectedOutputStream;
039:
040: /**
041: * This service is used to cryptographically protect incoming
042: * and outgoing messages.
043: * This service should be called by the transport service for
044: * all Cougaar messages.
045: */
046: public interface MessageProtectionService extends Service {
047:
048: /**
049: * Sign and/or encrypt the header of an outgoing message.
050: *
051: * When a message is sent out:
052: * 1) The aspect calls protectHeader().
053: * 2) The data protection service encrypts/signs the header.
054: * It uses the information provided in the source and destination
055: * to decide how to encrypt and/or sign.
056: * 3) The encrypted header is returned.
057: * 4) The aspect calls getOuputStream.
058: * - The source and destination should be the same as what was found
059: * in the call to protectHeader().
060: * 5) The service returns an output stream where the MTS will serialize
061: * the clear-text message.
062: * 6) The service encrypts the message and write the encrypte/signed
063: * message to the output stream.
064: * 7) The encrypted message is actually sent over the network.
065: *
066: * @param attributes data about the message for the header
067: * @param source The source of the message
068: * @param destination The destination of the message
069: * @return the protected header (sign and/or encrypted)
070: * @throws GeneralSecurityException
071: * @throws IOException
072: */
073: byte[] protectHeader(MessageAttributes attributes,
074: MessageAddress source, MessageAddress destination)
075: throws GeneralSecurityException, IOException;
076:
077: /**
078: * Verify the signed and/or encrypted header of an incoming message.
079: *
080: * @param rawData The signed and/or encrypted header
081: * @param source The source of the message
082: * @param destination The destination of the message
083: * @return the header in the clear
084: * @throws GeneralSecurityException
085: * @throws IOException
086: */
087: MessageAttributes unprotectHeader(byte[] rawData,
088: MessageAddress source, MessageAddress destination)
089: throws GeneralSecurityException, IOException;
090:
091: /**
092: * Gets a stream to encrypt and/or sign outgoing messages
093: *
094: * This method is called once for each outgoing message.
095: * The implementation of this service must construct a
096: * ProtectedOutputStream, which is a special kind of FilterOutputStream.
097: * The service client (MTS) serializes a Message to this
098: * ProtectedOutputStream. The implementation of the service will in turn
099: * write data to the 'os' stream it was given at creation time.
100: * When the Message has been completely serialized and written
101: * to the ProtectedOutputStream, the service client calls the finish()
102: * method of the ProtectedOutputStream.
103: *
104: * The first byte of the ProtectedOutputStream should be the first byte
105: * of the (serialized) message content.
106: *
107: * Since messages may be resent, the method may be called multiple times
108: * for the same message, but this is in a different context.
109: *
110: * @param os The output stream containing encrypted and/or signed data
111: * @param source The source of the outgoing message
112: * @param destination The destination of the outgoing message
113: * @param attrs The attributes of the outgoing message
114: * @return A filter output stream
115: * @throws IOException
116: */
117: ProtectedOutputStream getOutputStream(OutputStream os,
118: MessageAddress source, MessageAddress destination,
119: MessageAttributes attrs) throws IOException;
120:
121: /**
122: * Gets a stream to verify incoming messages
123: *
124: * This method is called once for each incoming message.
125: * The implementation of this service must construct a
126: * ProtectedInputStream, which is a special kind of FilterInputStream.
127: * The service reads an encrypted message from the ProtectedInputStream.
128: * The service client (MTS) calls the finishInput() method when all the
129: * message has been read.
130: * The service client verifies the message. The service client reads
131: * the clear-text message from the 'is' input stream.
132: *
133: * The first byte of the ProtectedInputStream should be the first byte
134: * of the (serialized) message content.
135: *
136: * Since messages may be resent, the method may be called multiple times
137: * for the same message, but this is in a different context.
138: *
139: * @param is The input stream containing the verified clear-text message
140: * @param src The source of the incoming message
141: * @param dst The destination of the incoming message
142: * @param attrs The attributes of the incoming message
143: * @return A filter intput stream
144: * @throws IOException
145: */
146: ProtectedInputStream getInputStream(InputStream is,
147: MessageAddress src, MessageAddress dst,
148: MessageAttributes attrs) throws IOException;
149: }
|