001 package org.apache.fulcrum.pbe;
002
003 import java.io.IOException;
004 import java.io.InputStream;
005 import java.io.OutputStream;
006 import java.security.GeneralSecurityException;
007
008 /*
009 * Licensed to the Apache Software Foundation (ASF) under one
010 * or more contributor license agreements. See the NOTICE file
011 * distributed with this work for additional information
012 * regarding copyright ownership. The ASF licenses this file
013 * to you under the Apache License, Version 2.0 (the
014 * "License"); you may not use this file except in compliance
015 * with the License. You may obtain a copy of the License at
016 *
017 * http://www.apache.org/licenses/LICENSE-2.0
018 *
019 * Unless required by applicable law or agreed to in writing,
020 * software distributed under the License is distributed on an
021 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
022 * KIND, either express or implied. See the License for the
023 * specific language governing permissions and limitations
024 * under the License.
025 */
026
027
028 /**
029 * Encapsulates an PBE (Password Based Encryption) functionality
030 * from the JCE (Java Crypto Extension).
031 *
032 * The service provides
033 * <ul>
034 * <li>method to create more or less secure passwords</li>
035 * <li>creation of cipher streams for transparent encryption/decryption</li>
036 * <li>generic encryption/decryption methods</li>
037 * <ul>
038 *
039 * @author <a href="mailto:siegfried.goeschl@it20one.at">Siegfried Goeschl</a>
040 */
041
042 public interface PBEService
043 {
044 /**
045 * Create a password based on the pre-defined seed.
046 *
047 * @return the password
048 * @throws Exception the password creation failed
049 */
050 char[] createPassword()
051 throws Exception;
052
053 /**
054 * Create a password based on the supplied seed.
055 *
056 * @param seed the seed value for the password generation
057 * @return the password
058 * @throws Exception the password creation failed
059 */
060 char[] createPassword( char[] seed )
061 throws Exception;
062
063 /**
064 * Creates a decrypting input stream.
065 *
066 * @param is the input stream to be wrapped
067 * @param password the password to be used
068 * @return an decrypting input stream
069 * @exception GeneralSecurityException accessing the JCE failed
070 * @exception IOException an IOException occured during processing
071 */
072 InputStream getInputStream( InputStream is, char[] password )
073 throws GeneralSecurityException, IOException;
074
075 /**
076 * Creates a smart decrypting input stream.
077 *
078 * @param is the input stream to be wrapped
079 * @param password the password to be used
080 * @return an decrypting input stream
081 * @exception GeneralSecurityException accessing the JCE failed
082 * @exception IOException an IOException occured during processing
083 */
084 InputStream getSmartInputStream( InputStream is, char[] password )
085 throws GeneralSecurityException, IOException;
086
087 /**
088 * Creates an encrypting output stream.
089 *
090 * @param os the output stream to be wrapped
091 * @param password the password to be used
092 * @return an decrypting input stream
093 * @exception GeneralSecurityException accessing the JCE failed
094 * @exception IOException an IOException occured during processing
095 */
096 OutputStream getOutputStream( OutputStream os, char[] password )
097 throws GeneralSecurityException, IOException;
098
099 /**
100 * Copies from a source to a target object using encryption.
101 *
102 * For he souce object the following data types are supported
103 * <ul>
104 * <li>String</li>
105 * <li>File</li>
106 * <li>byte[]</li>
107 * <li>char[]</li>
108 * <li>ByteArrayOutputStream</li>
109 * <li>InputStream</li>
110 * </ul>
111 *
112 * For target object the following data types are supported
113 *
114 * <ul>
115 * <li>File</li>
116 * <li>OutputStream</li>
117 * </ul>
118 *
119 * @param source the source object
120 * @param target the target object
121 * @param password the password to use for encryption
122 * @exception GeneralSecurityException accessing the JCE failed
123 * @exception IOException an IOException occured during processing
124 */
125 public void encrypt( Object source, Object target, char[] password )
126 throws GeneralSecurityException, IOException;
127
128 /**
129 * Copies from a source to a target object using decrpytion.
130 *
131 * For he souce object the following data types are supported
132 * <ul>
133 * <li>String</li>
134 * <li>File</li>
135 * <li>byte[]</li>
136 * <li>char[]</li>
137 * <li>ByteArrayOutputStream</li>
138 * <li>InputStream</li>
139 * </ul>
140 *
141 * For target object the following data types are supported
142 *
143 * <ul>
144 * <li>File</li>
145 * <li>OutputStream</li>
146 * </ul>
147 *
148 * @param source the source object
149 * @param target the target object
150 * @param password the password to use for decryption
151 * @exception GeneralSecurityException accessing the JCE failed
152 * @exception IOException an IOException occured during processing
153 */
154 public void decrypt( Object source, Object target, char[] password )
155 throws GeneralSecurityException, IOException;
156
157 /**
158 * Encrypts a string into a hex string.
159 *
160 * @param plainText the plain text to be encrypted
161 * @param password the password for encryption
162 * @return the encrypted string
163 * @exception GeneralSecurityException accessing the JCE failed
164 * @exception IOException an IOException occured during processing
165 */
166 String encryptString( String plainText, char[] password )
167 throws GeneralSecurityException, IOException;
168
169 /**
170 * Decrypts an encrypted string into the plain text. The encrypted
171 * string must be a hex string created by encryptString.
172 *
173 * @param cipherText the encrypted text to be decrypted
174 * @param password the password for decryption
175 * @return the decrypted string
176 * @exception GeneralSecurityException accessing the JCE failed
177 * @exception IOException an IOException occured during processing
178 */
179 String decryptString( String cipherText, char[] password )
180 throws GeneralSecurityException, IOException;
181 }