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    }