Table of Contents 1. Introduction 2. Instalación i. Introducción ii. Primera Instalación iii. Actualización iv. Configuración i. Configuración mobile services ii. Configuración viafirma platform iii. Configuración viafirma manager 3. Uso del API REST i. Securización OAuth 1.0 ii. Uso del cliente Postman iii. Uso del cliente Java iv. Uso del cliente Swagger 4. Uso de políticas de firma y evidencias i. Introducción ii. Firma digitalizada iii. Evidencias Electrónicas iv. Políticas de Firma 5. Uso del backend i. Panel de Control i. Auditoría de Mensajes ii. Configuración del Sistema iii. Gestión de Usuarios i. Roles iv. Información del Sistema i. Check de componentes ii. Uso en tiempo real v. Informe de Uso vi. Sistema de Transferencias ii. Administración i. Aplicaciones ii. Dispositivos iii. Grupos iv. Plantillas Página 2
iii. Actividad i. Buscador de Metadatos ii. Mensajes iii. Notificaciones iv. Desarrollo i. Códigos de Errores ii. Ejemplos de mensajes iii. Servicios Rest 6. Uso de formularios 7. Uso de plantillas 8. Procedimiento de actualización i. Histórico de cambios y versiones ii. Actualización 2.4.0 a 2.5.7 iii. Actualización a la versión 2.4.0 iv. Actualización a la versión 2.3.3 v. Actualización a la versión 2.3.0 vi. Actualización a la versión 2.2.12 vii. Actualización a la versión 2.2.11 viii. Actualización a la versión 2.2.9 ix. ANEXO: actualización 2.0 a 2.5 Página 3
Documentación de viafirma documents La solución viafirma documents incluye los siguientes componentes: Viafirma Platform Viafirma Manager Viafirma Mobile Services Viafirma Document ios Viafirma Document Android Documentación actualizada: 20-agosto-2015 Documentación actualizada para v2.5.8 de viafirma documents Introduction Página 4
Instalación Instalación Página 5
Introducción Prerequisitos Qué voy a necesitar para la instalación? Servidor de aplicaciones JEE (Tomcat o Weblogic), recomendado sobre Linux. Base de Datos (Oracle o Postgre) Qué dimensionamiento le dedico? Se tomará como ejemplo una instalación en un mismo servidor de aplicaciones. En caso de optar por una instalación en varios servidores, o instalación en clúster, consultar con el soporte técnico de viafirma las opciones recomendadas para cada caso. RAM: 8GB Micro: recomendado, 2 micros de 6 núcleos cada uno; a 2Ghz. Disco: 20 GB (1) Logs: estimado 1GB por cada millón de operaciones (1) Custodia: variable según peso y número de documentos firmados. Estimado inicial 20 GB. Logs de auditoría: estimado 1GB por cada millón de operaciones. Estimado incial 20 GB. (2) (1): los logs incluyen configuración de rotación, por lo que la optimización de estos logs podrá definirse por el administrador del sistema en función a las políticas de espacio en disco deseadas. (2): manager consumirá la auditoría volcada por viafirma platform y la persiste en su base de datos. Qué servicios externo voy a necesitar? Un certificado digital para la firma de documentos Una clave pública para el cifrado de datos biométricos Servicio de timestamping RFC3161 (ofrecido por una TSA - Timestamping Introducción Página 6
Authority) Servidor SMTP para el envío de correos. Restricción de Conexiones Externas Salidas con proxies Si se va a necesitar salir por un proxy, es necesario informar los datos de conexión para inlcuirlos en la configuración específica de conexión de cada componente. Es importante detectar antes de la instalación si existen mecanismos internos que puedan alterar las cabeceras http en las comunicaciones de red, pues el sistema implementa varios mecanismos de securización y autenticación, como Oauth y openid, sensible a este tipo de comportamiento y que haría inviable la instalación del servicio. Validación de Certificados Digitales Viafirma platform necesita verificar las fuentes de validación de las Entidades de Certificación (CA - Certificate Authority) que hayan emitido los certificados con los que se va a trabajar. Sólo en el caso de que el servidor donde esté instalado viafirma platform no tenga libre salida a internet, habrá que autorizar específicamente la lista de fuentes de validación que se deseen, como mínimo, al servicio OCSP, CRL o endpoint en el que poder verficar el root ca. Por ejemplo: http://ocsp.gse.com.co http://crl.gse.com.co/crl_sub001_ac_gse.crl http://crl1.gse.com.co/crl_sub001_ac_gse.crl http://certs.gse.com.co/sub/crt_sub01_ac_gse.crt Autoridad de Tiempo (TSA) Viafirma platform necesita conusmir los servicios de tiempo con las TSA contratadas o autorizadas por el cliente. Sólo en el caso de que el servidor donde esté instalado viafirma platform no tenga libre salida a internet, habrá que autorizar específicamente la lista de autoridades de tiempo que se deseen. Por ejemplo: Introducción Página 7
http://tsu2.camerfirma.com:8884/tsc Validación de Licencia En el arranque del servidor se realiza una comprobación remota de la validez de la licencia instalada. Para ello es necesaria tener salida a las siguientes URLs: https://services.viafirma.com/license/ http://services.viafirma.com/licence/ Proveedores de Notificaciones Push Se consumirán las APIs de los dos proveedores de notificaciones push, Google y Apple, para lo que hay que autorizar las siguientes salidas: Google Cloud Messaging (GCM) (1) https://android.googleapis.com/gcm/send Apple Push Notificaction (APN) (2) Producción: gateway.push.apple.com, port 2195 Desarrollo (sandbox): gateway.sandbox.push.apple.com, port 2195 (1) Documentación oficial de google: http://developer.android.com/google/gcm/http.html* (2) Documentación oficial de apple: https://developer.apple.com/library/ios/documentation/networkinginternet/conceptual/re motenotificationspg/chapters/communicatingwithaps.html#//apple_ref/doc/uid/tp400 08194-CH101-SW1* Introducción Página 8
Primera Instalación Entregables Kit de Instalación Se hará entrega de un kit de instalación con los siguientes recursos: war de mobile-services (backend) war de viafirma platform (firma) war de viafirma manager (gestión de firma) Por otro lado, se entregarán los scripts SQL para la instalación, en limpio, de los modelos de base de datos para Oracle y Postgre. mobile-services (backend) viafirma manager (gestión de firma) Por último, en el kit de instalación se encontrarán otros recursos necesarios para la instalación y que son referenciados en el proceso de instalación y/o configuración, como drivers JDBC, ejemplos de configuración, performance de tomcat, etc. Licencia Junto a los entregables, se hará entrega de la licencia de uso. licencia viafirma Kit de Desarrollo De forma adicional se podrá hacer entrega de recursos con utilidades para integradores, como aplicaciones de ejemplo, snippets de código, o certicados digitales de prueba. Instalación Base de Datos A partir de los scripts SQL entregados, se deberán crear los modelos de datos para Primera Instalación Página 9
mobile-services y para viafirma manager. Viafirma platform NO hace uso de base de datos, por ello no se hace entrega de ningún script SQL asociado a platform. Los datos de cada modelo de datos creado serán utilizados en la configuración de cada sistema, según se describe en el capítulo de configuración para cada componente. Despliegue Esta documentación de instalación está referida a una instalación típica en un contenedor Apache Tomcat, por lo que algunos detalles serán muy específicos de este contenedor, no coincidiendo en otros contenederos soportados, como por ejemplo Weblogic. copiar los tres wars proporcionados en la ruta de despliege del tomcat, por ejemplo: /home/viafirma/tomcat/webapps/ arrancar servidor /home/viafirma/tomcat/bin/catalina.sh start Si los wars ya estaban pre-configurados, se podrá acceder al servicio para comprobar su correcto arranque: En caso de que los wars no estuvieran pre-configurados, se deberá consultar el capítulo de configuración para la modificación de los respectivos ficheros de configuración. Tras el cambio, el servidor deberá ser parado y arrancado nuevamente para que la nueva configuración tenga efecto. /home/viafirma/tomcat/bin/catalina.sh stop /home/viafirma/tomcat/bin/catalina.sh start Tras el arranque, podremos consultar los frontales web para comprobar el servicio. Por ejemplo: http://192.168.10.20:8080/mobile-services Primera Instalación Página 10
http://192.168.10.20:8080/viafirmamanager http://192.168.10.20:8080/viafirma nota: la IP 192.168.10.20 es la que hay configurada en los ficheros de configuración de ejemplo. Sustituirla por la IP o nombre de dominio finalmente utilizada en la instalación. Primera Instalación Página 11
Actualización La instalación de actualizaciones de viafirma documents, o alguno de sus componentes, se describe en el capítulo 7 "Procedimiento de Actualización". Consulta tu versión y elije el procedimiento que corresponda. Actualización Página 12
1.4 Configuración Deberá consultarse con el responsable de la instalación en cada caso para confirmar la configuración de todos los componentes. En caso de que la instalación forme parte del servicio de soporte técnico contratado a viafirma, los wars podrían entregarse pre-configurados, o parcialmente preconfigurados. En caso de que la instalación no forme parte de ninguna gestión de la configuración contratada con viafirma, los wars entregados vendrán sin configuración personalizada, por lo que hay que consultar las instrucciones de configuración descritas en este capítulo. Configuración de mobile services (backend) Configuración de viafirma platform (firma) Configuración de viafirma manager (gestión de firma) Configuración Página 13
Configuración mobile services NOTA: documentación optimizada para la v2.5.8. de mobile-services. El backend de la solución cuenta con dos tipos de configuraciones: configuración estática el arranque configuración en el panel de control Ambas deben llevarse a cabo, se describen en los siguientes puntos. Configuración estática Como parte de la configuración "estática", tenemos: Configuración del Contexto El war entregado (mobile-services.war) espera un fichero de configuración mobileservices.xml, el cual se encontrará, tras el despliegue, en el directorio de configuración del contenedor de aplicaciones. Ej. para Apache Tomcat: /<tomcat-home>/conf/catalina/localhost/mobile-services.xml En otros contenedores, como WebLogic, la configuración se realiza en un fichero de propiedades (mobile-services.properties) en lugar del xml del contexto. En Apache Tomcat también se puede optar por la configuración con fichero.properties. En este caso, el fichero estaría ubicado en el siguiente path: /<tomcat-home>/webapps/mobile-services/web-inf/classes/config.properties En el siguiente link se encuentra un fichero de configuración de ejemplo: config.properties Configuración mobile services Página 14
NOTA: en la configuración de ejemplo se definen varias propiedades que hacen referencia a un path de filesystem. Dichos paths deben existir en el momento de la instalación, y con los permisos de escritura adecuados. Consulta aquí los paths necesarios para la configuración. Configuración de la Caché (hazelcast) De igual forma que para el contexto, el war entregado ya cuenta con una configuración para hazelcast. En caso de necesitar modificar esta configuración, habrá que modificar el fichero de configuración siguiente: /<tomcat-home>/webapps/mobile-services/web-inf/classes/hazelcast.xml En el siguiente link se encuentra un fichero de configuración de ejemplo: hazelcast.xml Configuración escritura de logs El war entregado ya cuenta con una configuración básica para la escritura de logs del backend. En caso de necesitar modificar esta configuración, habrá que modificar el fichero de configuración siguiente: /<tomcat-home>/webapps/mobile-services/web-inf/classes/logback.xml En el siguiente link se encuentra un fichero de configuración de ejemplo: logback.xml Configuración Dinámica Hasta aquí la configuración necesaria para el arranque del backend. A partir de aquí, el resto de parametrización del servicio se podrá hacer en caliente, desde el Panel de Control del backend, tal y como se detalla en el capítulo 4 "Uso del Backend > Panel de Control > Configuración del Sistema" Configuración mobile services Página 15
Configuración viafirma platform NOTA: documentación optimizada para la v3.8.0 de viafirma platform. Configuración del Contexto El war entregado (viafirma.war) espera un fichero de configuración viafirma.xml, el cual se encontrará, tras el despliegue, en el directorio de configuración del contenedor de aplicaciones. Ej. para Apache Tomcat: /<tomcat-home>/conf/catalina/localhost/viafirma.xml En el siguiente link se encuentra un fichero de configuración de ejemplo: viafirma.xml En otros contenedores, como WebLogic, la configuración se realiza en un fichero de propiedades (viafirmaconfig.properties) en lugar del xml del contexto. En Apache Tomcat también se puede optar por la configuración con fichero.properties. En este caso, el fichero estaría ubicado en el siguiente path: /<tomcat-home>/webapps/viafirma/web-inf/classes/viafirmaconfig.properties En el siguiente link se encuentra un fichero de configuración de ejemplo: viafirmaconfig.properties NOTA: en la configuración de ejemplo se definen varias propiedades que hacen referencia a un path de filesystem. Dichos paths deben existir en el momento de la instalación, y con los permisos de escritura adecuados. Consulta aquí los paths necesarios para la configuración. Configuración viafirma platform Página 16
Configuración de la Caché (ehcache) De igual forma que para el contexto, el war entregado ya cuenta con una configuración para ehcache. En caso de necesitar modificar esta configuración, habrá que modificar el fichero de configuración siguiente: /<tomcat-home>/webapps/viafirma/web-inf/classes/ehcache.xml En el siguiente link se encuentra un fichero de configuración de ejemplo: ehcache.xml IMPORTANTE: esta configuración de ehcache debe hacerse de forma conjunta con la configuración del ehcache de viafirma manager, o de lo contrario no podrían consumirse mutuamente. En concreto, prestar especial atención a la configuración multicastgroupaddress y un multicastgroupport. <cachemanagerpeerproviderfactory class="net.sf.ehcache.distribution.rmicachemanagerpeerproviderfactory" properties="peerdiscovery=automatic,multicastgroupaddress=230.0.0.1,multicastgroupport=4446 propertyseparator=","/> Path de Configuración Externa De forma opcional, este fichero de configuración de echache podría estar ubicado en un path externo al de despliegue. Para que este fichero "externo" pueda ser localizado durante el arranque, será necesario usar la variable VIAFIRMA_CONFIGURATION_PATH en la configuración del contexto, e indicar el path donde se encontrará el fichero de configuración para ehcache, por ejemplo: /home/viafirma/platform_config/ehcache.xml Configuración escritura de logs Configuración viafirma platform Página 17
El war entregado ya cuenta con una configuración básica para la escritura de logs. En caso de necesitar modificar esta configuración, habrá que modificar el fichero de configuración siguiente: /<tomcat-home>/webapps/viafirma/web-inf/classes/log4j.properties En el siguiente link se encuentra un fichero de configuración de ejemplo: log4j.properties Configuración viafirma platform Página 18
Configuración de viafirma manager NOTA: documentación optimizada para la v1.8.0 de viafirma manager. Configuración del Contexto El war entregado (viafirmamanager.war) espera un fichero de configuración viafirmamanager.xml, el cual se encontrará, tras el despliegue, en el directorio de configuración del contenedor de aplicaciones. Ej. para Apache Tomcat: /<tomcat-home>/conf/catalina/localhost/viafirmamanager.xml En el siguiente link se encuentra un fichero de configuración de ejemplo: viafirmamanager.xml En otros contenedores, como WebLogic, la configuración se realiza en un fichero de propiedades (viafirmaconfig.properties) en lugar del xml del contexto. En Apache Tomcat también se puede optar por la configuración con fichero.properties. En este caso, el fichero estaría ubicado en el siguiente path: /<tomcat-home>/webapps/viafirmamanager/web-inf/classes/viafirmaconfig.properties En el siguiente link se encuentra un fichero de configuración de ejemplo: viafirmaconfig.properties NOTA: en la configuración de ejemplo se definen varias propiedades que hacen referencia a un path de filesystem. Dichos paths deben existir en el momento de la instalación, y con los permisos de escritura adecuados. Consulta aquí los paths necesarios para la configuración. Configuración viafirma manager Página 19
Configuración de la Base de Datos La configuración de la base de datos será Oracle o Postgre. Una vez elegido el tipo de base de datos, hay que verificar que el persistence.xml se corresponda con la base de datos elegida. Este fichero se encuentra en: /<tomcat-home>/webapps/viafirmamanager/web-inf/classes/meta-inf/persistence.xml y habrá que revisar el DIALECTO seleccionado: <!-- <property name="hibernate.dialect" value="org.hibernate.dialect.postgresqldialect"/> --> <property name="hibernate.dialect" value="org.hibernate.dialect.oracle10gdialect"/> Si se opta por el fichero de configuración.properties en lugar del contexto.xml, en éste último sólo habrá que definir el pool de conexión a la base de datos. En el siguiente link se encuentra un contexto de ejemplo donde sólo se define el pool de conexión a la base de datos: viafirmamanager_only_pool_jdbc.xml Configuración de la Caché (ehcache) De igual forma que para el contexto, el war entregado ya cuenta con una configuración para ehcache. En caso de necesitar modificar esta configuración, habrá que modificar el fichero de configuración siguiente: /<tomcat-home>/webapps/viafirmamanager/web-inf/classes/ehcache.xml En el siguiente link se encuentra un fichero de configuración de ejemplo: ehcache.xml IMPORTANTE: esta configuración de ehcache debe hacerse de forma conjunta con la Configuración viafirma manager Página 20
configuración del ehcache de viafirma manager, o de lo contrario no podrían consumirse mutuamente. En concreto, prestar especial atención a la configuración multicastgroupaddress y un multicastgroupport. <cachemanagerpeerproviderfactory class="net.sf.ehcache.distribution.rmicachemanagerpeerproviderfactory" properties="peerdiscovery=automatic,multicastgroupaddress=230.0.0.1,multicastgroupport=4446 propertyseparator=","/> Path de Configuración Externa De forma opcional, este fichero de configuración de echache podría estar ubicado en un path externo al de despliegue. Para que este fichero "externo" pueda ser localizado durante el arranque, será necesario usar la variable VIAFIRMA_CONFIGURATION_PATH en la configuración del contexto, e indicar el path donde se encontrará el fichero de configuración para ehcache, por ejemplo: /home/viafirma/manager_config/ehcache.xml Configuración escritura de logs El war entregado ya cuenta con una configuración básica para la escritura de logs. En caso de necesitar modificar esta configuración, habrá que modificar el fichero de configuración siguiente: /<tomcat-home>/webapps/viafirmamanager/web-inf/classes/log4j.properties En el siguiente link se encuentra un fichero de configuración de ejemplo: log4j.properties Configuración viafirma manager Página 21
Uso del API REST Uso del API REST Página 22
Acceso al API Rest con OAuth 1.0 Documentación oficial de OAuth 1.0 Desde la administración de aplicaciones del backend, podremos configurar la seguridad de acceso al API dos formas: OAuth a nivel de aplicación OAuth a nivel de usuario OAuth 1.0 a nivel de aplicación Solo es necesario conocer las credenciales de acceso de la aplicación y en las peticiones solo se registra la información de la aplicación solicitante. Se deben de informar los parámetros 'Consumer Key' y 'Consumer Secret' de OAuth, como resultado en la cabecera de la petición http se debe de informar de lo siguiente, en el parámetro Authorization en el Header de la petición. OAuth realm="http://dev.viafirma.com/mobile-services/api/v1/messages", oauth_consumer_key="com.viafirma.mobile.services.crm", oauth_signature_method="hmac-sha1", oauth_timestamp="1422479283", oauth_nonce="kubrja", oauth_version="1.0", oauth_signature="zvpxpedplikqrni0tmq3gpzmzl0%3d" En las siguientes capturas podemos ver un ejemplo de acceso al API Rest con el cliente Postman: Securización OAuth 1.0 Página 23
OAuth 1.0 a nivel de usuario Sólo es necesario conocer las credenciales de acceso de la aplicación y los datos de acceso de un usuario válido en el sistema, en las peticiones solo se registra la información de la aplicación solicitante y del usuario solicitante. Se deben de informar los parámetros Consumer Key, Consumer Secret, Token y Token Secret de OAuth. Como resultado, en la cabecera de la petición http debemos informar el parámetro Authorization en el Header de la petición: OAuth realm="http://dev.viafirma.com/mobile-services/api/v1/oauth/accesstoken", oauth_consumer_key="com.viafirma.mobile.services.demo", oauth_token="48a0bad01f064a69a19d310c5d71c3b6", oauth_signature_method="hmac-sha1", oauth_timestamp="1423584275", oauth_nonce="dn876b", oauth_version="1.0", oauth_signature="8pi9lg7qvuyo0ioepcv%2bmx5qqjm%3d" En las siguientes capturas podemos ver un ejemplo de acceso al API REST con el cliente Postman: Securización OAuth 1.0 Página 24
En primer lugar necesitamos pedir un token de acceso haciendo uso de las credenciales de acceso a nuestra aplicación: Una vez tenemos un token de acceso tenemos que aceptarlo haciendo uso del token temporal y de los datos del usuario. Securización OAuth 1.0 Página 25
Tras esto, podremos usar el token durante un periodo de tiempo predefinido en el backend, por ejemplo, 30 min. Transcurrido este tiempo, el token caducará y tendremos que solicitar uno nuevo. Securización OAuth 1.0 Página 26
Ejemplo de token caducado Securización OAuth 1.0 Página 27
Uso del cliente Postman Ejemplos de Uso Recuperar un mensajes procesado GET a http://dev.viafirma.com/mobile-services/api/v1/documents/drafted/1422479367884r127/1422479 Construye PDF a partir de datos de mensaje En la pestaña de OAuth de postman tenemos que indicar los valores correctos en los campos 'Consumer Key' y 'Consumer Secret' tal cual podemos ver en la siguiente captura Realizar una petición: POST http://dev.viafirma.com/mobile-services/api/v1/messages Uso del cliente Postman Página 28
Enviando el siguiente json IMPORTANTE el código del workflow tiene que ser EX005 { "version" : "00001", "workflow" : { "code" : "EX005", "history" : [ ] }, "notification" : { "text" : "Generar pdf", "detail" : "Ejemplo que solo genera un pdf y ejecuta el callback según lo tenga configurado" }, "document" : { "templatecode" : "022_example", "templatetype" : "docx", "items" : [ { "key" : "KEY_01", "type" : "text", "label" : "KEY_01", "required" : true, "disabled" : false }, { "key" : "KEY_02", "type" : "text", "label" : "KEY_02", "required" : false, "disabled" : false }, { "key" : "KEY_03", "type" : "text", "label" : "KEY_03", "required" : false, "disabled" : false }, { "key" : "KEY_04", "type" : "text", "label" : "KEY_04", "required" : false, Uso del cliente Postman Página 29
} } "disabled" : false } ] Uso del cliente Postman Página 30
Mobile Services SDK Java Cliente Java para Mobile Services - Viafirma Histórico de cambios y versiones Integración en proyecto maven Es necesario añadir el siguiente repositorio <repository> <id>viavansi-repo</id> <name>viavansi Maven Repository</name> <url>http://repositorio.viavansi.com/repo</url> </repository> Añadir la siguiente dependencia <dependency> <groupid>com.viafirma</groupid> <artifactid>ms-sdk-java</artifactid> <version>2.x.x</version> </dependency> Ejemplo de uso: Recuperar información de un mensaje conocido el código Ejemplo de Autenticación OAuth a nivel de usuario V1Api api = new V1Api(); // URL de acceso al API REST api.setbasepath(urlapi); // OAuth consumer key api.setconsumerkey(consumerkey); // OAuth consumer secret Uso del cliente Java Página 31
api.setconsumersecret(consumersecret); // Solicitar un nuevo token Token token = V1oauthApi.getInstance().requestToken(); api.settoken(token.getoauth_token()); api.settokensecret(token.getoauth_token_secret()); // Aceptar el token recibido token = V1oauthApi.getInstance().accessToken(userCode, userpass, "client_auth"); api.settoken(token.getoauth_token()); api.settokensecret(token.getoauth_token_secret()); // Ejemplo de como recuperar un message conocido su código Message message = V1messagesApi.getInstance().getMessageByCode("1400834631788R255"); Ejemplo de envio de mensaje para solo generar documentos pdf Ejemplo de autenticación OAuth a nivel de aplicación V1Api api = new V1Api(); // URL de acceso al API REST api.setbasepath(urlapi); // OAuth consumer key api.setconsumerkey(consumerkey); // OAuth consumer secret api.setconsumersecret(consumersecret); //Create message Message message = new Message(); //Create workflow Workflow workflow = new Workflow(); workflow.setcode("ex005"); message.setworkflow(workflow); //Create notification info Notification notification = new Notification(); notification.settext("notification Demo"); notification.setdetail("generate a example document from template"); message.setnotification(notification); //Create a template document Document document = new Document(); document.settemplatecode("022_example"); document.settemplatetype("docx"); Uso del cliente Java Página 32
//Add dato to template List<Item> items = new ArrayList<Item>(); Item item = new Item(); item.setkey("key_01"); item.setlabel("test key 1"); item.setvalue(uuid.randomuuid().tostring()); items.add(item); item = new Item(); item.setkey("key_02"); item.setlabel("test key 2"); item.setvalue(uuid.randomuuid().tostring()); items.add(item); item = new Item(); item.setkey("key_03"); item.setlabel("test key 3"); item.setvalue(uuid.randomuuid().tostring()); items.add(item); item = new Item(); item.setkey("key_04"); item.setlabel("test key 4"); item.setvalue(uuid.randomuuid().tostring()); items.add(item); document.setitems(items); message.setdocument(document); //Send message String messagecode = V1messagesApi.getInstance().sendMessage(message); Uso del cliente Java Página 33
Uso del cliente Swagger [documentación de ayuda próximamente disponible] Uso del cliente Swagger Página 34
Uso de políticas de firma y evidencias 3.1 Introducción 3.2 Firma Digitalizada 3.3 Evidencias Electrónicas 3.4 Políticas de Firma Uso de políticas de firma y evidencias Página 35
Introducción Estructura de los documentos firmados Firma del documento PDF El PDF será firmado electrónicamente, con un certificado digital, y dependiendo de la política de firma indicada en el JSON se realizará en un formato de firma que incluya un sello de tiempo (hora oficial). Dependiendo de las evidencias capturadas durante el proceso de firma, el PDF mostrará tantas anotaciones como evidencias se hayan capturado, referenciando en cada caso al XML asociado, el cual estará disponible como anexo al propio PDF, por tanto, podremos encontrarnos con PDFs que tengan más de un XML asociado. Introducción Página 36
Además, al PDF se le insertará como anexo el XML que se describe en el siguiente punto. Firma de los XML adjuntos al PDF El XML contendrá datos relativos a la operación de firma digitalizada o cualquier evidencia capturada durante el proceso. Parte de la información recogida en este XML irá en claro y otra parte irá cifrada. Esta última se cifrará en función de la política de cifrado indicada en el JSON. Además, el XML estará firmado electrónicamente, con un certificado digital, y dependiendo de la política de firma indicada en el JSON se realizará en un formato de firma que incluya un sello de tiempo (hora oficial). Entre los datos que se recogen en el XML también encontraremos datos asociados de forma biunívoca al PDF que el usuario firmó. Introducción Página 37
Introducción Página 38
Firma digitalizada Parámetros de configuración Ayuda contextual Para incluir un texto de ayuda en el lienzo de firma que se muestra en el dispositivo móvil, usaremos el parámetro digitalizedsignhelptext. { } "key": "digitalizedsignhelptext", "value": "Firma de ejemplo" Posición de la firma digitalizada En la política podemos determinar si la firma capturada se puede insertar libremente en el documento, haciendo doble tap sobre el documento, o bien insertarla en una posición conocida. Para ello, se usarán los siguientes parámetros: signpositionenable: lo usaremos para permitir la posición manual de la firma. Los valores permitidos son true y false. En caso de indicar false en el parámetro signpositionenable, necesitamos los siguientes parámetros: { } "key": "signpositionenable", "value": "false" digitalizedsignrectangle: lo usaremos para definir dónde insertar la firma, en el formato: Y, X, width, height { } "key": "digitalizedsignrectangle", "value": "{\"y\":\"240\",\"x\":\"270\",\"width\":\"160\",\"height\":\"65\"}" Firma digitalizada Página 39
page: para indicar el número de la página donde se insertará la firma. Para insertarlo en la última se indica -1. { } "key": "page", "value": "1" Tipos de cifrado Usaremos el parámetro op para indicar qué tipo de operación de cifrado se va a realizar. Los valores permitidos son dos: pen = el cifrado se realiza en servidor biometric = el cifrado se realiza en el propio dispositivo móvil { } "key": "op", "value": "pen" Clave pública de un certificado informado Usaremos la siguiente combinación: op = pen biometricalias y biometricpass existe están informados: Como resultado tendremos un XML cifrado en servidor con la clave pública del certificado indicado, el cual previamente fue instalado en el servidor. Ejemplo: { "key": "op", "value": "pen" }, { "key": "biometricalias", "value": "viafirmadocuments" Firma digitalizada Página 40
}, { "key": "biometricpass", "value": "12345" }, { "key": "DIGITALIZED_SIGNATURE_FORMAT", "value": "XADES_EPES_ENVELOPED" } En el ejemplo anterior además hemos informado el parámetro DIGITALIZED_SIGNATURE_FORMAT para que el XML también sea firmado con el certificado informado, y que también debió ser instalado en el servidor previamente. Clave pública informada en el propio JSON Usaremos la siguiente combinación: op = biometric biometriccryptopem nota: si nos informan una clave pública en el JSON, usaremos preferentemente el tipo de operación cifrado en local (dispositivo móvil). Como resultado tendremos un XML cifrado en el dispositivo móvil, con la clave pública informada en el parámetro biometriccryptopem. Ejemplo: { "key": "op", "value": "biometric" }, { "key": "biometriccryptopem", "value": "MIIFbDCCBFSgAwIBAgIIGtUapa" }, { "key": "biometricalias", "value": "viafirmadocuments" }, { "key": "biometricpass", "value": "12345" }, { "key": "DIGITALIZED_SIGNATURE_FORMAT", Firma digitalizada Página 41