amap-firma

Última modificación por Administrator el 2019/10/08 14:46

AMAPFirma-3.3.8 2019/09/30

Cambio de package de las excepciones.
Uso del componente de amap-sw-cliente

AMAPFirma-3.3.7 2019/08/20

Nueva forma de upgrade a traves del nivel de firma

AMAPFirma-3.3.6 2019/04/24

Nuevo metodo de obtener información de firma
Filtro de reintentos mas completo
Correcciones menores

AMAPFirma-3.3.5 2019/03/26

Paso de UUID para firmados u originales

AMAPFirma-3.3.4 2019/03/07

Correcciones menores

AMAPFirma-3.3.3 2019/03/04

Uso de clases comunes en amap-firma-modelo
Cambio de nombres

AMAPFirma-3.3.2 2019/02/25

Adaptación a los cambios de amap-firma-modelo

AMAPFirma-3.3.1 2019/02/19

Corrección en el unmarshaling de las fechas
Obtener metadatos de la base de datos al obtener una firma 

AMAPFirma-3.3.0 2019/02/12

Incorporada conexión con amap-firma-servidor

AMAPFirma-3.2.5 2019/01/29

Añadida información adicional a las respuestas (tipo de firma e idPeticion) y otras correcciones menores.

AMAPFirma-3.2.4 2019/01/28

Cambio de libreria de bcprov

AMAPFirma-3.2.3 2017/07/03

Correcciones de dependencias menores

AMAPFirma-3.2.2 2017/06/30

Eliminar dependencia indirecta

AMAPFirma-3.2.1 2017/06/5

Ajustes en las dependencias

AMAPFirma-3.2.0 2017/05/21

Se incluyen una implementación httpclient.
Se añade la posibilidad de indicar el timeout para las realización de las peticiones.

AMAPFirma-3.1.1 2017/01/10

Se incluyen los certificados firmantes en la respuesta de las operaciones de firma.

AMAPFirma-3.1.0 2016/06/29

Se incluyen campos de política para las firmas y campos de país, clasificación, seudónimo, cerqCualificated y cerqClasification.
Se añade el método de obtención del documento firmado con sus sucesivos resellados.

AMAPFirma-3.0.3 2015/05/11

Se incluye el campo del certificado público en base 64

AMAPFirma-3.0.2 2015/04/01

Se añade soporte de multifirma para el upgrade 

AMAPFirma-3.0.1 2015/02/09

Se añaden campos con información adicional en la información de los certificados:
 - tipoCertificado
 - numeroIdentificacionPersonal
 - unidadOrganizativa
 - puesto

AMAPFirma-3.0.0 2014/04/30

1- Se añaden métodos de firma, verificaciones y actualizaciones de firmas longevas
2- Se añade método de verificacion de sellos de tiempo

AMAPFirma-2.2 2012/10/31

1- Se introduce informacion de los sellados de tiempo.
2- Bug: se independiza el tratamiento de caracteres especiales.

AMAPFirma-2.1 2012/05/14

Se aumenta el tiempo de timeout por defecto a 1 minuto.

AMAPFirma-2.0 2011/11/11

Se migra el componente a Axis2.

<dependency>
<groupId>es.gobcantabria.amap.integracion</groupId>
<artifactId>amap-firma</artifactId>
<version>3.3.8</version>
</dependency>

Solicitar alta en plataforma de firma por medio del  Formulario de solicitud de alta en Plataforma de Firma

Sin recursos disponibles.

Configuración

Creación del cliente

Para la utilización del componente amap-firma basta con añadir la dependencia de maven.

Para instanciar el cliente, simplemente debemos escribir la siguiente línea:

AmapFirmaServiceInterface clienteMtom = AmapFirmaServiceFactory.getService(base, implementacion, timeout, aplicacion);

El servicio concreto a usar se definirá a partir de un fichero de properties junto con el resto de los parámetros:

KeyDescripciónEjemplo
sistemas.global.amap.firma.url.baseEndpoint del servicio webhttps://******/amap-firma-servidor
sistemas.app.amap.firma.implementacionTipo de Implementacion (Ver notas de actualización)mtom
sistemas.app.amap.firma.timeoutTimeout 120000
sistemas.app.amap.firma.idaplicacionIdentificador de la aplicacióngobcant.aplicacion1

Valores permitidos para la propiedad implementación: mtom

Se puede establecer un timeout para la ejecución de las peticiones utilizando la propiedad de sistemas correspondiente.

Los valores de las propiedades aquí mostrados son meramente ilustrativos. En los entornos de desarrollo / preproducción y producción los valores de las variables han de ser externalizados tal y como se especifica en el documento Definición de acceso a propiedades de sistema

...
sistemas.global.amap.firma.url.base=https://******/amap-firma-servidor
...

Ejemplo de contenido del fichero de sistemas_nombreApp.properties:

...
sistemas.app.amap.firma.implementacion=mtom
sistemas.app.amap.firma.timeout=120000
sistemas.app.amap.firma.idaplicacion=gobcant.aplicacion1
sistemas.app.amap.firma.aliascertificado=/* El alias del certificado de firma que usa la aplicación para firmar*/
...

Los parámetros que se deben indicar obligatoriamente en el método son la URL de conexión con el Web Services, el tipo de implementación y el identificador de la aplicación.

Notas de actualización

Si se actualiza el componente desde la versión anterior es necesario el uso de una de las opciones descritas en los apartados siguientes.

Rápida(No recomendada)

Para un paso rápido, pero no completo, se añade al antiguo constructor; la nueva url del servicio y el identificador dela aplicación. Ejemplo:

FirmaFacade firmaFacade = new FirmaFacade(null, null, timeout, base, aplicacion);

Nota: Esta opción estará disponible temporalmente, desapareciendo por completo la antigua implementación y teniendo que hacer el cambio completo indicado en el siguiente apartado.

Completa(Recomendada)

Esta implementación sera completa, usando la nueva configuración y el traspaso de todos los metodos de la antigua implementación a la nueva. 

Notas generales

  • En los nuevos métodos se podrá indicar el usuario que realiza la acción. Si no se indica, se entenderá a la aplicación como la autora de la acción.
  • Para el traspaso de los ficheros no sera necesario pasarlos a base64, aceptando como parámetro un byte array o un InputStream (Para realizar una firma se permitire pasar un String en base64).
  • Junto con la firma se podrá realizar el upgrade simultaneo, en caso de pasar al método un tipo de firma upgradeable. Ejemplo: CADES_T
  • En caso de error la nueva implementación devolverá una excepción, de la que se podrá obtener información del error.

Equivalencia de métodos

A continuación se enlazan los métodos antiguos con su nueva implementación:

getDocumento = obtenerFirmaCustodiada
getDocumentoResellado = obtenerFirmaCustodiada
getFecha = obtenerTimestamp
checkCertificado = comprobarCertificado
firmaServidor = firmar
firmaPDFServidor = firmar
firmaServidorGenerico = firmar
verificaFirmaPDF = verificarFirma //El parámetro operationID se sustituye por el boolean custodiar (autentica = no custodiar) 
verificaFirma = verificarFirma //El parámetro operationID se sustituye por el boolean custodiar (autentica = no custodiar) 
verificaFirmaDSS = verificarFirma //El parámetro operationID se sustituye por el boolean custodiar (autentica = no custodiar) 
actualizaFirma = mejorarFirma
--verificaTimeStamp-- //Método sin equivalencia. Contacten con el grupo de arquitectura si es necesario
--verificaTimeStampExterno-- //Método sin equivalencia. Contacten con el grupo de arquitectura si es necesario
--getCAs-- //Método sin equivalencia. Contacten con el grupo de arquitectura si es necesario

Nota: La descripción detallada de los métodos anteriormente expuestos y de algunos más se encuentra en la pestaña de uso.

N/A

Nombreamap-firma
Identificadoramap-firma
Grupoes.gobcantabria.amap.integracion
Versión3.3.8
Licencia
DesarrolladorGobierno de Cantabria
Descripción

Componente de integración con la Plataforma de Firma Digital corporativa.

Documentaciónamap-firma (JavaDoc)
Binarioamap-firma (Jar)
Dependenciasamap-firma (Librerías)

Sin particularidades. Seguir las recomendaciones del fabricante.

Detalles iniciales

El traspaso de ficheros se realiza en binario a excepción del método firmar que permite además un String en base64.

En todos los métodos se solicita el usuario que realiza la petición, habitualmente el usuario logueado en ese momento. La mejor forma de obtenerlo en spring es: 

Authentication authentication = SecurityContextHolder.
          getContext().getAuthentication();
String usuario = authentication.getName();

Para obtener la información del error se deberá acceder a la variable de excepción, al objeto ErrorInfo y dentro de este se encuentra el código de error y la descripción técnica del mismo. Ejemplo:

e.getErrorInfo().getDescripcionTecnica();

Todos los objetos de respuesta contendrán el identificador de petición.

Todos los métodos pueden lanzar la excepción AmapFirmaException que contendrá información detallada del error, indicando su código y descripción. El catálogo completo de los códigos de error se encuentra en el enumerado: es.gobcantabria.amap.utilidades.amapfirmamodelo.ws.soap.mtom.exception.ErrorEnum.

Se permite el paso firmas y originales a través del UUID del gestor documental. Para ello, se deberá solicitar el acceso de AMAP-FIRMA al espacio documental de los ficheros

Ejemplos de uso

Firmar un documento

El método firmar permite realizar una firma de cualquier nivel. La opción recomendada es la que no tiene tipo de firma, de esa manera obtendría la de por defecto de la aplicación. Un ejemplo de su uso seria el siguiente:

byte[] original =  /*Se cargaría el documento*/
String aliasCertificado = "certificado.aplicacion1"
TipoFirma tipoFirma = TipoFirma.CADES_T //Opcional
boolean custodiar = true //Opcional

FirmaRespuesta firmaRespuesta = clienteMtom.firmar(original, aliasCertificado, usuario, tipoFirma, custodiar);

Se pasan como parámetros:

  • El documento original a firmar, siendo aceptado como tipo de dato:
    • Un String en base64
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • El alias del certificado con el que se va a firmar. Normalmente definido en la variable de sistema sistemas.app.amap.firma.aliascertificado
  • El usuario que realiza la petición.
  • El objeto TipoFirma. Opcional, si no se introduce valor se cogerá el valor por defecto de la aplicación
  • Si se quiere custodiar el documento. Opcional, por defecto true

La respuesta es un objeto que contiene la información de la firma.

Verificar una firma

El método verificarFirma permite comprobar si la firma que se ha realizado sobre un documento es valida. Un ejemplo de su uso seria el siguiente:

byte[] original =  /*Se cargaría el documento*/ //Opcional
byte[] firma =  /*Se cargaría el documento*/
boolean custodiar = true //Opcional

FirmaRespuesta firmaRespuesta = clienteMtom.verificarFirma(original, firma, usuario, custodiar);

Se pasan como parámetros 

  • El documento original (Opcional cuando la firma contenga el original), siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • La firma, siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • El usuario que realiza la petición.
  • Si se quiere custodiar el documento. Opcional, por defecto true

La respuesta es un objeto que contiene la información de la firma, si es correcta o no y un mensaje informativo del error o de la validación.

Mejorar una firma

El método mejorarFirma permite mejorar la firma de un documento. Un ejemplo de su uso seria el siguiente:

byte[] original =  /*Se cargaría el documento*/; //Opcional
byte[] firma =  /*Se cargaría el documento*/;
TipoFirma tipoFirma = TipoFirma.CADES_C;
byte[] certificadoFirmaActualizar = /*Se cargaria el documento*/; //Opcional
boolean incluirCertificados = true; //Opcional

FirmaRespuesta firmaRespuesta = clienteMtom.mejorarFirma(original, firma, tipoFirma, usuario, certificadoFirmaActualizar, incluirCertificados );

Se pasan como parámetros 

  • El documento original (Opcional cuando la firma contenga el original), siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • La firma, siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • La actualización de la firma
  • El usuario que realiza la petición.
  • El binario de uno de los certificados que se uso para firmar. Opcional, si no se pasa ningún valor se actualizaran todos
  • Si se quiere añadir información extra en la vuelta, como por ejemplo los certificados, el sello de tiempo .... Opcional, por defecto true

La respuesta es un objeto que contiene la información de la nueva firma, si es correcta o no y un mensaje informativo del error o de la mejora.

Comprobar la validez de un certificado

El método comprobarCertificado permite comprobar la validez de un certificado pasado por parámetro. Un ejemplo de su uso seria el siguiente:

byte[] certificado= /*Se cargaría el certificado*/

Certificado certificado=clienteMtom.comprobarCertificado(certificado, usuario);

Se pasan como parámetros 

  • El certificado, siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
  • El usuario que realiza la petición.

La respuesta es un objeto que contiene si el certificado es valido o no y la información del certificado.

Obtener sello de tiempo

 

El método obtenerTimestamp permite obtener el sello de tiempo. Un ejemplo seria el siguiente:

long idFirmaCustodiada=1234; //Opcional

Timestamp firmaCustodiada=clienteMtom.obtenerTimestamp(idFirmaCustodiada, usuario);

Los parámetros que se pasan son:

  • El identificador del documento en la Plataforma de Firma. Opcional, sino se pasa devolverá un sello de tiempo basado en un valor aleatorio.
  • El usuario que realiza la petición.

La respuesta es un objeto que contiene un array de bytes con el sello de tiempo.

Obtener firma custodiada


El método obtenerFirmaCustodiada permite recuperar un documento almacenado en custodia. Un ejemplo de su recuperación seria el siguiente:

long idDocumento=1234;
boolean incluirDocumento = true; //Opcional
boolean incluirMetadatos = true; //Opcional
boolean incluirDocumentoResellado = false; //Opcional

FirmaCustodiada firmaCustodiada=clienteMtom.
                              obtenerFirmaCustodiada(idDocumento, incluirDocumento, incluirMetadatos, incluirDocumentoResellado, usuario);

Los parámetros que se pasan son:

  • El identificador del documento en la Plataforma de Firma.
  • Un booleano que indica si quiere incluir el documento. Opcional, por defecto true.
  • Un booleano que indica si quiere obtener los metadatos. Opcional, por defecto true.
  • Un booleano que indica si quiere obtener la firma resellada. Opcional, por defecto false.
  • El usuario que realiza la petición.

La respuesta es un objeto que contiene la firma con las distintas opciones respecto a los parámetros introducidos.

NOTA: En el objeto devuelto vendrá el documento indicando si esta o no custodiado a través de un boolean.

Obtener el tipo de firma de un documento

El método obtenerTipoFirma permite obtener el tipo de firma con el que se realizo una firma. Un ejemplo de su uso seria el siguiente:

byte[] firma= /*Se cargaría la firma*/

TipoFirmaRespuesta tipoFirmaRespuesta=clienteMtom.obtenerTipoFirma(firma, usuario);

Se pasan como parámetros 

  • La firma, siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • El usuario que realiza la petición.

La respuesta es un objeto que contiene el tipo de firma con el que se realizo la firma.

Obtener el tipo de firma por defecto

El método obtenerTipoFirmaPorDefecto permite obtener el tipo de firma por defecto en la aplicación. Un ejemplo de su uso seria el siguiente:

TipoFirmaRespuesta tipoFirmaRespuesta=clienteMtom.obtenerTipoFirmaPorDefecto(usuario);

Se pasan como parámetros 

  • El usuario que realiza la petición.

La respuesta es un objeto que contiene el tipo de firma por defecto.

Obtener el tipo de firma en cliente por defecto

El método obtenerTipoFirmaClientePorDefecto permite obtener el tipo de firma en cliente por defecto en la aplicación. Un ejemplo de su uso seria el siguiente:

TipoFirmaRespuesta tipoFirmaRespuesta=clienteMtom.obtenerTipoFirmaClientePorDefecto(usuario);

Se pasan como parámetros 

  • El usuario que realiza la petición.

La respuesta es un objeto que contiene el tipo de firma en cliente por defecto.

Obtener la información firma de un documento

El método obtenerInformacion permite obtener toda la información posible de firma de un documento, devolviendo si los hubiera los posibles errores en una lista. Un ejemplo de su uso seria el siguiente:

InputStream original= /*Se cargaría la firma*/ //Opcional
InputStream firma= /*Se cargaría la firma*/

ObtenerInformacion obtenerInformacion=clienteMtom.obtenerInformacion(original, firma, usuario);

Se pasan como parámetros 

  • La original (Opcional cuando la firma contenga el original), siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • La firma, siendo aceptado como tipo de dato:
    • Un array de bytes
    • Un InputStream
    • Un UUID
  • El usuario que realiza la petición.

La respuesta es un objeto que contiene la firma con la información disponible y una lista de errores si los hubiera.

Listado de códigos de error con su descripción

Todos los errores enumerados a continuación se encuentra en: es.gobcantabria.amap.utilidades.amapfirmamodelo.ws.soap.mtom.exception.ErrorEnum.


//Errores en la petición
000 -> Error desconocido
001 -> Error en la información de la peticion : {idPeticion}
002 -> El campo {campo no informado} es obligatorio
003 -> El campo {campo mal informado} tiene un valor incorrecto, los valores soportados son {valores soportados}
004 -> La aplicación {nombre de la aplicacion} no está dada de alta en la plataforma de firma
005 -> La aplicación {nombre de la aplicacion} no está activa
006 -> El documento con id {idFirmaCustodiada} no está en la plataforma de firma
007 -> La firma con el hash no está permitida para tipo de firma {tipo de firma solicitada} solamente para XAdES
008 -> La autenticación ha sido incorrecta
009 -> El tipo de firma efectivo no se ha podido obtener
010 -> El documento {original o firmado} con uuid {uuidDocumento} no se ha podido acceder.
           ¿Se han solitado los permisos de acceso para AMAP-FIRMA-SERVIDOR al gestor documental donde se encuentra el documento?.

//Errores al obtener documento
100 -> El documento {idFirmaCustodiada} no se ha podido obtener

//Errores al firmar
200 -> No se ha podido realizar la firma: {idFirmaCustodiada}
201 -> El tipo de firma {tipo de firma solicitado} no es compatible con integr@
202 -> Error generando la firma con integr@
203 -> El tipo de firma {tipo de firma solicitado} no está soportado para la generación de firmas
204 -> El tipo de firma {tipo de firma generado} generado no está soportado
205 -> El tipo de firma {tipo de firma generado} generado no corresponde con el solicitado {tipo de firma solicitado}
206 -> No se ha podido almacenar la firma generada en la petición {idPeticion}
207 -> No se ha podido generar la respuesta en la peticion {idPeticion}
208 -> El documento orginal se encuentra firmado y no es valido

//Errores al mejorar
300 -> No se ha podido realizar el upgrade: {mensaje de error}
301 -> No se ha podido realizar la verificación del upgrade: {mensaje de error}
302 -> No se ha podido realizar el upgrade porque el documento {idFirmaCustodiada} no se se encuentra custodiado
303 -> El tipo de firma de este documento no es un tipo upgradeable
304 -> El nivel de firma {nivelFirma} no es valido para un tipo PADES
304 -> El nivel solicitado es inferior o igual al del documento(Nivel del documento: {TipoFirma del documento}).
399 -> No se ha podido realizar el upgrade por un error desconocido: {mensaje de error}

//Errores al verificar
499 -> No se ha podido realizar correctamente la verificación: {mensaje de error}

//Errores al comprobar certificado
500 -> El certificado {aliasCertificado} no se ha podido comprobar: {mensaje de error}
501 -> El certificado {aliasCertificado} no es válido: {mensaje de error}
502 -> El certificado no es válido: {motivo del rechazo}

//Errores al conectarse al gestor documental
600 -> Fallo al conectarse al servicio del gestor documental
601 -> Error al convertir el archivo a documento de alfresco
602 -> No existe el documento en el gestor documental

//Errores de custodia
800 -> No se ha podido obtener el documento insertado en custodia
801 -> No se ha podido añadir la firma a custodia
802 -> No se ha podido añadir la firma a custodia: {mensaje de error}
803 -> No se ha podido insertar el documento con id {idFirmaCustodiada} en custodia
804 -> El tipo de firma no está soportado
805 -> No se ha podido obtener el documento de custodia
806 -> No se ha podido obtener el binario del documento en custodia
807 -> No se ha podido obtener las propiedades de custodia del documento
808 -> No se ha podido obtener la firma resellada de custodia del documento
809 -> No se ha podido guardar el temporal de un fichero a custodiar
810 -> No se ha podido recuperar el registro de la firma pendiente de custodia con id {idFirmaCustodiada}
811 -> No se ha podido obtener el documento con id {idFirmaCustodiada} en custodia
812 -> No se ha podido insertar el sello de tiempo del documento con id {idFirmaCustodiada} en custodia
813 -> El tipo de custodia {tipo de custodia} no tiene url
814 -> El documento con id {idFirmaCustodiada} no está en custodia ni pendiente de custodia
815 -> Del documento con error de custodia con el id {idFirmaCustodiada} no se ha podido borrar {firma, original o ambos}
816 -> No se encuentra el documento original en una firma dettached
817 -> No se ha podido instanciar el servicio
818 -> El documento en custodia con el id {idFirmaCustodiada} no se ha podido realizar el borrado {fisico o logico}

//Errores de @Firma
900 -> Error parseando la url del servicio DSS de verificación
901 -> El tipo de @firma {tipo de firma} no está soportado
902 -> No se ha podido determinar el tipo de @firma
903 -> La URL de @firma {url@FirmaAfirma} es incorrecta
904 -> La URL de @firma {url@FirmaTsa} es incorrecta
905 -> No se pudo leer el contenedor de certificados
906 -> No se pudo  codificar la parte pública del certificado
907 -> El certificado con el alias {aliasCertificado} no se ha encontrado en el contenedor de certificados
908 -> La aplicación {nombre de la aplicacion} no tiene ningún certificado con alias {aliasCertificado} asociado
909 -> Tipo de firma {tipo de firma} no soportado
910 -> Tipo de firma {tipo de firma} no soportado para la operación solicitada ({operacion solicitada})
911 -> El tipo de firma no se pudo obtener
912 -> Error almacenando la información del timestamp
913 -> No se ha podido obtener el identificador de custodia del sello de tiempo del documento, posiblemente esté en proceso su custodia

//Errores de transformación
1001 -> El valor {valor} indicado para la propiedad {propiedad} no es válido
1002 -> Fallo en la transformación de la fecha string {valorFecha} en la variable {variableTransformada} usando el patrón {patronTransformacion}

© 2014 GOBIERNO DE CANTABRIA - AVISO LEGAL Y PROTECCIÓN DE DATOS