/*
* Controlador Java de la Secretaria de Estado de Administraciones Publicas
* para el DNI electronico.
*
* El Controlador Java para el DNI electronico es un proveedor de seguridad de JCA/JCE
* que permite el acceso y uso del DNI electronico en aplicaciones Java de terceros
* para la realizacion de procesos de autenticacion, firma electronica y validacion
* de firma. Para ello, se implementan las funcionalidades KeyStore y Signature para
* el acceso a los certificados y claves del DNI electronico, asi como la realizacion
* de operaciones criptograficas de firma con el DNI electronico. El Controlador ha
* sido disenado para su funcionamiento independiente del sistema operativo final.
*
* Copyright (C) 2012 Direccion General de Modernizacion Administrativa, Procedimientos
* e Impulso de la Administracion Electronica
*
* Este programa es software libre y utiliza un licenciamiento dual (LGPL 2.1+
* o EUPL 1.1+), lo cual significa que los usuarios podran elegir bajo cual de las
* licencias desean utilizar el codigo fuente. Su eleccion debera reflejarse
* en las aplicaciones que integren o distribuyan el Controlador, ya que determinara
* su compatibilidad con otros componentes.
*
* El Controlador puede ser redistribuido y/o modificado bajo los terminos de la
* Lesser GNU General Public License publicada por la Free Software Foundation,
* tanto en la version 2.1 de la Licencia, o en una version posterior.
*
* El Controlador puede ser redistribuido y/o modificado bajo los terminos de la
* European Union Public License publicada por la Comision Europea,
* tanto en la version 1.1 de la Licencia, o en una version posterior.
*
* Deberia recibir una copia de la GNU Lesser General Public License, si aplica, junto
* con este programa. Si no, consultelo en <http://www.gnu.org/licenses/>.
*
* Deberia recibir una copia de la European Union Public License, si aplica, junto
* con este programa. Si no, consultelo en <http://joinup.ec.europa.eu/software/page/eupl>.
*
* Este programa es distribuido con la esperanza de que sea util, pero
* SIN NINGUNA GARANTIA; incluso sin la garantia implicita de comercializacion
* o idoneidad para un proposito particular.
*/
package es.gob.jmulticard.card.cwa14890;
import java.io.IOException;
import java.security.cert.CertificateException;
import java.security.interfaces.RSAPrivateKey;
import es.gob.jmulticard.apdu.connection.ApduConnectionException;
/** Interfaz con los métodos necesarios para la operación de las tarjetas
* acordes a la especificación CWA-14890.
* @author Carlos Gamuci */
public interface Cwa14890Card {
/** Verifica la CA intermedia del certificado de componente de la tarjeta.
* @throws CertificateException Cuando ocurre algún problema en la
* validación del certificado
* @throws IOException Cuando ocurre algún problema en la selección
* y lectura del certificado
* @throws SecurityException Si falla la validación de la CA */
void verifyCaIntermediateIcc() throws CertificateException, IOException;
/** Verifica el certificado de componente de la tarjeta.
* @throws CertificateException Cuando ocurre algún problema en la
* validación del certificado
* @throws IOException Cuando ocurre algún problema en la selección
* y lectura del certificado
* @throws SecurityException Si falla la validación del certificado */
void verifyIcc() throws CertificateException, IOException;
/** Recupera el certificado de componente codificado.
* @return Certificado codificado
* @throws IOException Cuando ocurre algún problema en la selección
* y lectura del certificado */
byte[] getIccCertEncoded() throws IOException;
/** Verifica que los certificados declarados por el controlador (certificados de
* Terminal) sean válidos para el uso de la tarjeta.
* @param consts Clase de claves.
* @throws ApduConnectionException Cuando ocurre algín error en la
* comunicación con la tarjeta
* @throws es.gob.jmulticard.apdu.connection.cwa14890.SecureChannelException Cuando ocurre algún error en la
* verificación de los certificados */
void verifyIfdCertificateChain(final Cwa14890PublicConstants consts) throws ApduConnectionException;
/** Obtiene el mensaje de autenticación interna de la tarjeta.
* @param randomIfd Bytes aleatorios generados
* @param chrCCvIfd CHR de la clave pública del certificado de Terminal
* @return Mensaje cifrado con la clave privada de componente de la tarjeta
* @throws ApduConnectionException Cuando ocurre un error de comunicación con la tarjeta */
byte[] getInternalAuthenticateMessage(final byte[] randomIfd, final byte[] chrCCvIfd) throws ApduConnectionException;
/** Envia el mensaje de autenticación externa.
* @param extAuthenticationData Mensaje de autenticación externa
* @return {@code true} si la autenticación finalizó correctamente, {@code false} en caso contrario
* @throws ApduConnectionException Cuando ocurre un error en la comunicación con
* la tarjeta */
boolean externalAuthentication(final byte[] extAuthenticationData) throws ApduConnectionException;
/** Establece una clave pública y otra privada para la autenticación
* interna y externa de la tarjeta.
* @param refPublicKey Referencia a la clave pública.
* @param refPrivateKey Referencia a la clave privada.
* @throws es.gob.jmulticard.apdu.connection.cwa14890.SecureChannelException Cuando ocurre un error durante el proceso de autenticación
* @throws ApduConnectionException Cuando ocurre un error de comunicación con la tarjeta. */
void setKeysToAuthentication(final byte[] refPublicKey, final byte[] refPrivateKey) throws ApduConnectionException;
/** Solicita un desafío de 8 bytes a la tarjeta.
* @return Array de 8 bytes aleatorios.
* @throws ApduConnectionException Cuando ocurre un error de comunicación con la tarjeta */
byte[] getChallenge() throws ApduConnectionException;
/** Recupera el numero de serie de la tarjeta.
* @return Número de serie
* @throws ApduConnectionException Cuando ocurre un error en la comunicación con
* la tarjeta */
byte[] getSerialNumber() throws ApduConnectionException;
/** Recupera la referencia a la clave privada del certificado de Componente.
* @param consts Clase de claves.
* @return Referencia a clave privada */
byte[] getRefIccPrivateKey(final Cwa14890PublicConstants consts);
/** Recupera el CHR de la clave pública del certificado de Terminal.
* @param consts Clase de claves.
* @return Referencia a clave pública */
byte[] getChrCCvIfd(final Cwa14890PublicConstants consts);
/** Recupera la clave privada del certificado de componente del terminal.
* @param consts Clase de claves privadas.
* @return Clave privada */
RSAPrivateKey getIfdPrivateKey(final Cwa14890PrivateConstants consts);
/** Obtiene la longitud, <u>en octetos</u>, de las claves RSA del certificado de
* comnponente del terminal.
* @param consts Clase de claves.
* @return Longitud, <u>en octetos</u>, de las claves RSA del certificado de
* comnponente del terminal. */
int getIfdKeyLength(final Cwa14890PublicConstants consts);
}