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 }