// This Source Code is in the Public Domain per: http://unlicense.org
package org.litesoft.encryption.symmetric;

public interface SymmetricEncryptor
{
    public class DecryptFailureException extends IllegalArgumentException
    {
        public DecryptFailureException( char pChar, Class pSymmetricEncryptorClass )
        {
            super( pSymmetricEncryptorClass.getName() + " can not decrypt the character ('" + pChar + "' / " + ((int) pChar) + ")." );
        }
    }

    /**
     * @return a non-null SHORT string with NO leading or trailing whitespace that contains an Idetifier
     *         for the Implementation and a Version Number (colons ':' are NOT allowed to be in this String)
     */
    String getIdentifierAndVersion();

    /**
     * Encrypt the pClearText.
     *
     * @param pClearText - null ok
     *
     * @return null if pClearText was null, otherwise the Encrypted version of the pClearText
     *
     * @throws IllegalArgumentException
     */
    String encrypt( String pClearText );

    /**
     * Decrypt the pEncryptedText (previously encrypted with encrypt().
     *
     * @param pEncryptedText - null ok
     *
     * @return null if pEncryptedText was null, otherwise the Decrypted version of the pEncryptedText (encrypted w/ encrypt()).
     *
     * @throws DecryptFailureException if the pEncryptedText can not be decrypted!
     */
    String decrypt( String pEncryptedText )
            throws DecryptFailureException;
}