/*******************************************************************************
* Copyright (c) 2008 Cambridge Semantics Incorporated.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* File: $Source$
* Created by: Matthew Roy ( <a href="mailto:mroy@cambridgesemantics.com">mroy@cambridgesemantics.com </a>)
* Created on: Jul 15, 2008
* Revision: $Id$
*
* Contributors:
* Cambridge Semantics Incorporated - initial API and implementation
*******************************************************************************/
package org.openanzo.security.keystore;
import org.openanzo.exceptions.AnzoException;
/**
* Component for encrypting strings and for handling the encrypted data in base64 encoding. The various encryption and decryption methods should be used in
* their corresponding pairs or the data may be corrupted. In particular:
* <ul>
* <li>encryptAndBase64EncodeString corresponds to decryptAndBase64DecodeString</li>
* <li>encryptAndBase64EncodeBytes corresponds to decryptAndBase64DecodeBytes</li>
* <li>encryptString corresponds to decryptString</li>
* <li>encryptBytes corresponds to decryptBytes</li>
* </ul>
* Mixing calls that don't correspond as described above can cause data corruption. For example,
* <code>new String(decryptBytes(encryptString("my plaintext")))</code>, will compile but the result from <code>decryptBytes</code> may be incorrect due to
* character encoding issues. If you ensure that the corresponding methods are used together, then no corruption due to character encoding issues can happen.
*
* Similarly, decrypting base64-encoded data which was base64-encoded outside of this class could cause data corruption. Different base64 encoding
* implementations may use different alphabets, may chunk the text into various lines, and may pad the text differently. The best practice is to only use these
* methods to decrypt data which was encrypted with the corresponding method.
*
* @author Jordi A. Albornoz Mulligan <a href="mailto:jordi@cambridgesemantics.com">jordi@cambridgesemantics.com</a>
*
*/
public interface ISecretKeystore {
/**
* Encrypts the given string and base64 encodes the encrypted data. The Base64 encoding doesn't chunk the data into fixed-width lines.
*
* To avoid data corruption due to character-encoding issues, you should only decrypt the results with the {@link #decryptAndBase64DecodeString(String)}
* method.
*
* @param plaintext
* string to encrypt
* @return base64-encoded encrypted string.
* @throws AnzoException
*/
public abstract String encryptAndBase64EncodeString(String plaintext) throws AnzoException;
/**
* Encrypts the given byte array and base64 encodes it. The Base64 encoding doesn't chunk the data into fixed-width lines.
*
* To avoid data corruption due to character-encoding issues, you should only decrypt the results with the {@link #decryptAndBase64DecodeBytes(String)}
* method.
*
* @param plaintext
* bytes to encrypt
* @return base64-encoded encrypted string.
* @throws AnzoException
*/
public abstract String encryptAndBase64EncodeBytes(byte plaintext[]) throws AnzoException;
/**
* Encrypts the given string.
*
* To avoid data corruption due to character-encoding issues, you should only decrypt the results with the {@link #decryptString(byte[])} method.
*
* @param plaintext
* string to encrypt
* @return encrypted data
* @throws AnzoException
*/
public abstract byte[] encryptString(String plaintext) throws AnzoException;
/**
* Encrypts the given bytes.
*
* To avoid data corruption due to character-encoding issues, you should only decrypt the results with the {@link #decryptBytes(byte[])} method.
*
* @param plaintext
* bytes to encrypt
* @return encrypted data
* @throws AnzoException
*/
public abstract byte[] encryptBytes(byte plaintext[]) throws AnzoException;
/**
* Decodes the given base64-encoded string and then decrypts the decoded string.
*
* To avoid data corruption due to character-encoding issues, you should only use this to decrypt strings that were encrypted by the
* {@link #encryptAndBase64EncodeString(String)} method.
*
* @param base64encodedCyphertext
* string to decrypt
* @return decrypted string
* @throws AnzoException
*/
public abstract String decryptAndBase64DecodeString(String base64encodedCyphertext) throws AnzoException;
/**
* Decodes the given base64-encoded string and then decrypts the decoded data.
*
* To avoid data corruption due to character-encoding issues, you should only use this to decrypt data that was encrypted by the
* {@link #encryptAndBase64EncodeBytes(byte[])} method.
*
* @param base64encodedCyphertext
* string to decrypt
* @return decrypted bytes
* @throws AnzoException
*/
public abstract byte[] decryptAndBase64DecodeBytes(String base64encodedCyphertext) throws AnzoException;
/**
* Decrypts the given data into a string.
*
* To avoid data corruption due to character-encoding issues, you should only use this to decrypt strings that were encrypted by the
* {@link #encryptString(String)} method.
*
* @param cyphertext
* data to decrypt
* @return decrypted string
* @throws AnzoException
*/
public abstract String decryptString(byte cyphertext[]) throws AnzoException;
/**
* Decrypts the given data.
*
* To avoid data corruption due to character-encoding issues, you should only use this to decrypt data that was encrypted by the
* {@link #encryptBytes(byte[])} method.
*
* @param cyphertext
* data to decrypt
* @return decrypted data
* @throws AnzoException
*/
public abstract byte[] decryptBytes(byte cyphertext[]) throws AnzoException;
/**
* Start the keystore
*
* @throws AnzoException
*/
public void start() throws AnzoException;
/**
* Stop the keystore
*
* @throws AnzoException
*/
public void stop() throws AnzoException;
}