01: /*
02: * <copyright>
03: *
04: * Copyright 1997-2004 Networks Associates Technology, Inc
05: * under sponsorship of the Defense Advanced Research Projects
06: * Agency (DARPA).
07: *
08: * You can redistribute this software and/or modify it under the
09: * terms of the Cougaar Open Source License as published on the
10: * Cougaar Open Source Website (www.cougaar.org).
11: *
12: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
13: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
14: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
15: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
16: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
17: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
18: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
19: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
20: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
22: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23: *
24: * </copyright>
25: *
26: * CHANGE RECORD
27: * -
28: */
29:
30: package org.cougaar.core.service;
31:
32: import java.io.IOException;
33: import java.io.InputStream;
34: import java.io.OutputStream;
35:
36: import org.cougaar.core.component.Service;
37:
38: /**
39: * This service is used by persistence to sign/encrypt an
40: * {@link OutputStream} and verify/decrypt an {@link InputStream}.
41: */
42: public interface DataProtectionService extends Service {
43:
44: /**
45: * Protects a data stream by signing and/or encrypting the stream.
46: * The service client should create an output stream to which the
47: * encrypted and/or signed data should be persisted.
48: * <p>
49: * This service will return an OutputStream that the client should
50: * use to write the unprotected data. The encrypted key that must
51: * be used to decrypt the stream will be placed in the key
52: * envelope. The client is responsible for retaining the encrypted
53: * key and providing it when the stream is subsequently decrypted.
54: * The encrypted key is usually a symmetric key encrypted with the
55: * public key of the agent.
56: * <p>
57: * This service must be able to re-encrypt symmetric keys at any time.
58: * For instance, keys may be re-encrypted if the certificate containing
59: * the public key is about to expire, or if the certificate is revoked.
60: * <p>
61: * In order to get access to keys at any time, the client must
62: * implement the DataProtectionServiceClient interface,
63: * which provides an iterator over all the key envelopes into which
64: * keys have been placed. The client is responsible for storing the
65: * envelope, so that it is available in the Iterator.
66: *
67: * @param pke provides a place to store the key used to encrypt the stream
68: * @param os the output stream containing the encrypted and/or signed data
69: * @return An output stream that the client uses to protect data.
70: */
71: OutputStream getOutputStream(DataProtectionKeyEnvelope pke,
72: OutputStream os) throws IOException;
73:
74: /**
75: * Unprotects a data stream by verifying and/or decrypting the stream.
76: * <p>
77: * The client should provide a key envelope having the same key
78: * that was used to encrypt the data.
79: *
80: * @param pke provides a place to retrieve the key for decrypting the stream
81: * @param is the input stream containing the encrypted and/or signed data
82: * @return An input stream containing the un-encrypted and/or verified data.
83: */
84: InputStream getInputStream(DataProtectionKeyEnvelope pke,
85: InputStream is) throws IOException;
86: }
|