package mixconfig.tools.dataretention.smartcard;

import java.util.Date;
import java.util.List;
import java.util.Map;

import anon.crypto.MyRSAPublicKey;

import mixconfig.tools.dataretention.smartcard.commands.ErrorCodeException;

public interface ISmartCard {

	// Stateless operations
	/**
	 * Get the version of the software on the smart card.
	 * 
	 * @return Version number as MAJOR.MINOR
	 * @throws ErrorCodeException
	 */
	public String getVersion() throws ErrorCodeException;

	/**
	 * Returns a list of the login names of all administrators.
	 * 
	 * @return
	 */
	public List<String> getAdministrators();

	/**
	 * Returns a list of the login names of all operators.
	 * 
	 * @return
	 */
	public List<String> getOperators();

	/**
	 * Returns the minimal number of valid administrator (name, pin) pairs
	 * needed to gain admin permission.
	 * 
	 * @return
	 * 
	 * @see #commitTransaction(Map)
	 * @see #resetLog(Map)
	 */
	public int getNeededNumberOfAdministrators();

	/**
	 * Returns the minimal number of valid operator (name, pin) pairs needed to
	 * gain operator permission.
	 * 
	 * @return
	 * 
	 * 
	 * @see #getSymmetricKeyForLogFiles(int)
	 */
	public int getNeededNumberOfOperators();

	/**
	 * Returns the minimal number of timeservers to be requested to set the date
	 * in the card.
	 * 
	 * @return
	 */
	public int getNeededNumberOfTimeservers();

	/**
	 * Returns true, iff administrators can be added/removed after the card is
	 * initialized.
	 * 
	 * @return
	 */
	public boolean isAllowedToModifyAdministrators();

	/**
	 * Returns true, iff operators can be added/removed after the card is
	 * initialized.
	 * 
	 * @return
	 */
	public boolean isAllowedToModifyOperators();

	/**
	 * Returns true, iff timeservers can be added/removed after the card is
	 * initialized.
	 * 
	 * @return
	 */
	public boolean isAllowedToModifyTimeServers();

	/**
	 * Returns true, iff the card has been initialized already.
	 * 
	 * @return
	 */
	public boolean isInitialized();

	/**
	 * Returns a list of all (timeserver, public key) pairs.
	 * 
	 * @return
	 */
	public Map<String, String> getTimeServers();

	/**
	 * Returns a list of all log entries.
	 * 
	 * @return
	 */
	public List<LogEntry> getLog();

	/**
	 * Returns the date, set on the SmartCard.
	 * 
	 * @return
	 * @throws ErrorCodeException
	 *             - if the date is not set on the SmartCard
	 */
	public Date getDate() throws ErrorCodeException;

	/**
	 * Changes the pin of the administrator name from oldPin to newPin, if the
	 * (name, oldPin) pair is correct. This operation is performed instantly and
	 * needs no transaction.
	 * 
	 * @param name
	 * @param oldPin
	 * @param newPin
	 * @throws ErrorCodeException
	 * 
	 * @see {@link #startTransaction()}
	 */
	public void changeAdministratorPin(String name, String oldPin, String newPin) throws ErrorCodeException;

	/**
	 * Changes the pin of the operator name from oldPin to newPin, if the (name,
	 * oldPin) pair is correct. This operation is performed instantly and needs
	 * no transaction.
	 * 
	 * @param name
	 * @param oldPin
	 * @param newPin
	 * @throws ErrorCodeException
	 * 
	 * @see {@link #startTransaction()}
	 */
	public void changeOperatorPin(String name, String oldPin, String newPin) throws ErrorCodeException;

	/**
	 * Resets the log on the card, if the admin permissions is granted. Admin
	 * permission is only granted, iff all administrators (name, pin) sent with
	 * the commit request are disjunct and correct and if administrator.size()
	 * >= neededNumberOfAdministrators (
	 * {@link #getNeededNumberOfAdministrators()}).
	 * 
	 * The reseted log will contain an entry, that the log was reseted and by
	 * whom.
	 * 
	 * @param administrators
	 *            Administrators: Name -> Pin mapping
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 */
	public void resetLog(Map<String, String> administrators) throws ErrorCodeException, IllegalArgumentException;

	/**
	 * Resets the card, if the admin permissions is granted. Admin permission is
	 * only granted, iff all administrators (name, pin) sent with the commit
	 * request are disjunct and correct and if administrator.size() >=
	 * neededNumberOfAdministrators ( {@link #getNeededNumberOfAdministrators()}
	 * ).
	 * 
	 * After reseted the Smartcard is not initialized anymore and all
	 * configurations, logs and any local states are removed. The private/public
	 * key pair of the card will be lost permanently.
	 * 
	 * The log will contain an entry, that the card was reseted and by whom.
	 * 
	 * @param administrators
	 *            Administrators: Name -> Pin mapping
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 */
	public void resetCard(Map<String, String> administrators) throws ErrorCodeException, IllegalArgumentException;

	// Encryption / Decryption
	/**
	 * Returns a random number from the Smartcard, which is supposed to use to
	 * verify the communication with the timeserver and avoid replay attacks.
	 * 
	 * TODO: really needed in interface and not only in inner logic?
	 * 
	 * @return
	 */
	public int getRandomNumberForTimeServerCommunication();

	/**
	 * Returns the public key of the SmartCard
	 * 
	 * @return
	 * @throws ErrorCodeException
	 *             - throw, iff no public key exists (if the card is not yet
	 *             initialized)
	 */
	public MyRSAPublicKey getPublicKey() throws ErrorCodeException;

	/**
	 * TODO: javaDoc
	 * 
	 * TODO: return type?
	 * 
	 * @param encryptedSymmetricKey
	 * @param valid operator (name, PIN) pairs
	 * @return
	 */
	public int getSymmetricKeyForLogFiles(int encryptedSymmetricKey, Map<String, String> operators);

	/**
	 * Sets date as current Date on the SmartCard.
	 * 
	 * TODO: implement signed communication with a timestamp server
	 * 
	 * @param date
	 *            - must not be null
	 */
	public void setDate(Date date) throws IllegalArgumentException, ErrorCodeException;

	// configuration changes in transactions
	/**
	 * Changes to the configuration of the SmartCard can only be performed in a
	 * transaction. The changes will only be applied, if the transaction is
	 * committed properly (@link {@link #commitTransaction(Map)}).
	 * 
	 * If this method is called, while a transaction is ongoing, all changes
	 * done in the old transaction won't be performed.
	 */
	public void startTransaction();

	/**
	 * Unless the card is not initialized ({@link #isInitialized()}), this
	 * method will throw a {@link ErrorCodeException}.
	 * 
	 * On initialization of the card, it can be allowed or prohibited to
	 * add/remove administrators, operators or timeservers after the
	 * initialization. Those settings cannot be changed no more.
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param allowedToModifyAdministrators
	 * @param allowedToModifyOperators
	 * @param allowedToModifyTimeServers
	 * @throws ErrorCodeException
	 */
	public void setPermissionChangeSettings(boolean allowedToModifyAdministrators, boolean allowedToModifyOperators, boolean allowedToModifyTimeServers) throws ErrorCodeException;

	/**
	 * Adds a administrator to the cards configuration, if it is allowed to
	 * modify administrators
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}.
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param name
	 * @param pin
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 */
	public void addAdministrator(String name, String pin) throws ErrorCodeException, IllegalArgumentException;

	/**
	 * Removes the administrator name from the cards configuration, if it is
	 * allowed to modify administrators
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}.
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param name
	 * @throws ErrorCodeException
	 */
	public void removeAdministrator(String name) throws ErrorCodeException;

	/**
	 * Adds a operator to the cards configuration, if it is allowed to modify
	 * operators {@link #setPermissionChangeSettings(boolean, boolean, boolean)}
	 * .
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param name
	 * @param pin
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 */
	public void addOperator(String name, String pin) throws ErrorCodeException, IllegalArgumentException;

	/**
	 * Removes the operator name from the cards configuration, if it is allowed
	 * to modify operators
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}.
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param name
	 * @throws ErrorCodeException
	 */
	public void removeOperator(String name) throws ErrorCodeException;

	/**
	 * Adds a timeserver to the cards configuration, if it is allowed to modify
	 * timeservers
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}.
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param uri
	 * @param publicKey
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 */
	public void addTimeServer(String uri, String publicKey);

	/**
	 * Removes the timeserver with the uri from the cards configuration, if it
	 * is allowed to modify timeservers
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}.
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param uri
	 * @throws ErrorCodeException
	 */
	public void removeTimeServer(String uri);

	/**
	 * Sets the minimal number of administrators, needed to perform an
	 * operation, which requires admin permission. This number can only be
	 * changes, if it is allowed to modify administrators (
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}).
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param number
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 * 
	 * @see #commitTransaction(Map)
	 * @see #resetLog(Map)
	 */
	public void setNeededNumberOfAdministrators(int number) throws ErrorCodeException, IllegalArgumentException;

	/**
	 * Sets the minimal number of operators, needed to perform an operation,
	 * which requires operator permission. This number can only be changes, if
	 * it is allowed to modify operators (
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}).
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param number
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 * 
	 * @see #getSymmetricKeyForLogFiles(int))
	 */
	public void setNeededNumberOfOperators(int number) throws ErrorCodeException, IllegalArgumentException;

	/**
	 * Sets the minimal number of timeservers, which must be contacted to set
	 * the current date of the card. This number can only be changes, if it is
	 * allowed to modify timeservers (
	 * {@link #setPermissionChangeSettings(boolean, boolean, boolean)}).
	 * 
	 * This method must be performed in a transaction
	 * {@link #startTransaction()}.
	 * 
	 * @param number
	 */
	public void setNeededNumberOfTimeServers(int number);

	/**
	 * Aborts the ongoing transaction. No changes will be applied to the
	 * configuration of the card.
	 */
	public void abortTransaction();

	/**
	 * Commits a transaction and thus activates all configuration changes made
	 * since {@link #startTransaction()}, if the admin permissions is granted.
	 * Admin permission is only granted, iff all administrators (name, pin) sent
	 * with the commit request are disjunct and correct and if
	 * administrator.size() >= neededNumberOfAdministrators (
	 * {@link #getNeededNumberOfAdministrators()}).
	 * 
	 * The transaction will be aborted otherwise.
	 * 
	 * On FIRST INITIALIZATION of a card (if !{@link #isInitialized()}), the
	 * admin permission is granted on default, regardless of the administrators
	 * parameter.
	 * 
	 * @param administrators
	 *            Administrators: Name -> Pin mapping
	 * @throws ErrorCodeException
	 * @throws IllegalArgumentException
	 */
	public void commitTransaction(Map<String, String> administrators) throws ErrorCodeException, IllegalArgumentException;
}