Manual de integrador

Transcripción

1 Bit4id Ibérica C/ Marie Curie, 8-14 Forum Nord de Tecnología Barcelona España Tel Bit4id Portugal Alameda Bonifácio Lázaro Lozano Nº 13, Ed. B, 1º E Oeiras - Portugal Tel: info.pt@bit4id.com Bit4id Italia Via Coroglio, 57 Città della Scienza Napoli Italia Tel Info.it@bit4id.com Bit4id Perú Avda. Olavegoya, nº 1835 Jesús María Lima Perú Tel grc@bit4id.com Bit4id UK 2 London Wall Buildings London Wall, London EC2M 5UU United Kingdom Tel info.uk@bit4id.com ISO 9001:2008 ISO 14001:2004 ISO 27001:2005

2 Sumario Revisiones... 3 Introducción... 4 Descripción de componentes... 4 Flujo de trabajo general... 4 Requisitos y preparación del escenario de pruebas... 7 Descripción técnica para el desarrollo

3 Revisiones Revisiones Fecha Cambios Autor /07/2013 Primera redacción DC /07/2013 Primera revisión y adaptación corporativa GSA /07/2013 Revisión técnica JGM /07/2013 Revisión y aprobación RLG /07/2013 Corrección RLG /07/2013 Corrección de estilo GSA /07/2013 Actualizaciones adaptadas a client 1.0a JGM /07/2013 Revisión y aprobación RLG /09/2013 Incorporación de Autenticación en aplicación web JGM /10/2013 Agrupados los manuales para Apache, IIS y manual para server. CSC /03/2014 Actualización apartados IIS y Apache CSC 1.10 LITE 09/03/2014 Adaptación LITE del manual JGM 1.11LITE Ampliación apartado Flujo de trabajo general JGM - CSC Revisiones 3

4 Introducción Este documento describe el proceso que sigue para la ejecución de firma así como el flujo de trabajo de las diferentes partes involucradas en este. Además, se expone al detalle el método de ejecución de dicho sistema y el análisis exhaustivo del código necesario para dicha ejecución. Esta versión del manual está pensada para la realización de pruebas de desarrollo y funcionamiento en un entorno de testeo, en el que algunos de sus componentes son proporcionados por Bit4id como se detalla en futuros apartados. Descripción de componentes Los sistemas que interactúan para llevar a cabo el proceso de firma son: 1. Application Server (en adelante AS): Este es el servidor web en el cual se quiere integrar el servicio de firma digital de o lo que es lo mismo el sitio web donde los usuarios accederán para solicitar la firma de documentos; 2. server (en lo sucesivo 4S): Linux daemon o servicio de Windows que realiza la comunicación entre el navegador y client. Se puede entender como un servidor web que se encarga de ejecutar el cliente de firma. 3. Navegador Web (en adelante, WB) del usuario final: Los navegadores compatibles son Internet Explorer (versión 6 o superior), Firefox y Chrome (versiones respaldadas por sus respectivos fabricantes). 4. Bit4id client (en adelante 4C): El software que se ejecuta en el usuario final y que es encargado de ejecutar la firma. Para facilitar la comprensión del proceso de firma lo enfocaremos desde el punto de vista del usuario con un ejemplo práctico. El sitio web ficticio donde el usuario final accederá para firmar sus documentos se llamará firmadedocumentos.bit4id.com (expuesta por el AS). En este sitio web habrá un área privada con una serie de documentos web (en formato PDF) que están a la espera de ser firmados por parte del usuario. El usuario tiene una tarjeta con su certificado digital. Flujo de trabajo general El proceso de firma seguiría los siguientes pasos: 1. Usuario ejecuta su explorador o WB e intenta acceder a firmadedocumentos.bit4id.com 2. El explorador o WB llama a AS y este le devuelve el contenido de firmadedocumentos.bit4id.com 3. Cuando el usuario accede a su sección privada aparecerá una lista con todos los documentos pendientes de firmar y el usuario seleccionará el documento que quiere firmar. En este momento se establece la conexión con 4S. 4. En este momento, tras clicar al botón Firmar Documento del archivo a firmar, se llama a 4C pasándole todos los parámetros de firma Introducción 4

5 5. 4C guía la usuario en todo el proceso de firma (solicita PIN, carga certificados y muestra documento y sube al AS el documento firmado). 6. Tas la firma, se cierra 4C y el usuario vuelve de nuevo a firmadedocumentos.bit4id.com En el punto 3 y 4 no se especifica cómo se realiza la llamada al 4S pues es la parte más característica de, la detallamos a continuación. Para llamar a es necesaria una implementación en el código web de AS. Siguiendo el ejemplo: En el código de la sección privada del usuario donde se encuentra la lista de documentos con el botón Firmar Documento, en cada archivo pendiente de firmar, se debe añadir: - Un formulario (uno por documento) con los parámetros de firma. Ejemplo: //Ubicación del documento a firmar <div class="bit4iddocument"> div> //Identificador del documento firmado que se generará tras finalizar el proceso <div class="bit4id-documentid">documento_a_firmar01</div> //Estandar de firma <div class="bit4id-signaturetype">pades</div> - Un script que carga el WB y que tiene como objetivo establecer la comunicación con el 4S //Llamada al script <script src=" // as-demo.bit4id.org es la url de 4S Cada formulario tiene como submit el botón Firmar Documento. <input type="submit" disabled="disabled" value="firmar Documento" /> Cuando el usuario clica a Firmar Documento y puesto que la comunicación ya ha sido establecida, el WB ya sabrá cómo tiene que ejecutar 4C y con qué parámetros realizar la firma. En este momento, llegamos al punto 5 que es donde 4C guía al usuario en el proceso de firma (transparente desde el punto de vista de integración). Una vez finalizado el proceso de firma debemos almacenar el documento. Para ello vamos a volver al formulario donde se indica el identificador del archivo firmado: //Identificador del documento firmado que se generará tras finalizar el proceso <div class="bit4id-documentid">_01_firmado</div> Puesto que tras la firma del usuario, queremos redirigir al usuario a una nueva sección, donde se le informe que el proceso se ha realizado correctamente y se le permita descargar el documento firmado. Para ello deberemos primero recoger el documento en cuestión. Flujo de trabajo general 5

6 La URL donde se recogerá el documento firmado, se especifica en el formulario inicial: //Se especifica la URL donde se puede recoger el documento firmado <form class="bit4id-sign" method="post" action="area_privada/sign-ok.php"> Esta sección llamada sign-ok.php deberá contener lo siguiente: - Definición de un nombre para el documento firmado //Seleccionamos el nombre del fichero temporal firmado $name = preg_replace("/[^a-z0-9._-]/i", "_", $myfile["name"]); //Utilizamos la función pathinfo para posteriormente obtener la extensión del archivo ($parts["extension) $parts = pathinfo($name); //Igualamos el valor de la variable name al nombre del documento $name=$_post["documentid"].".".$parts["extension"]; Donde documentid es una variable conocida por cuyo valor es igual al de bit4iddocumentid del formulario inicial. //Identificador del documento firmado que se generará tras finalizar el proceso <div class="bit4id-documentid">_01_online</div> - Ubicación del documento firmado //Se guarda el documento en la carpeta especificada del AS $success = move_uploaded_file($myfile["tmp_name"],$name); - Redirección a la sección que se le mostrará al usuario //Pasamos por parámetro la ubicación del documento firmado a través del parámetro file header("location: sign-end-ok.php?file=".$name); La redirección comentada en el párrafo anterior será la URL donde informaremos al usuario de la finalización del proceso y de la ubicación del documento: //Llamamos al parámetro file para conseguir el documento <p> Su documento ha sido firmado correctamente</p> <a href="<?php echo $_GET['file'];?> /> Pulse aquí para descargarlo </a> El proceso a nivel más técnico se detalla a continuación: Flujo de trabajo general 6

7 Requisitos y preparación del escenario de pruebas El escenario para la realización de las pruebas de desarrollo y funcionamiento es el siguiente: 1. Application Server (AS): Esta tarea del integrador la preparación y desarrollo de este componente. El desarrollo puede partir de los ejemplos adjuntos a esta documentación server (4S): Se debe utilizar el server que Bit4id ha expuesto en la siguiente URL: 3. Navegador Web (WB): Navegador instalado en la máquina del usuario. Los navegadores compatibles son Internet Explorer (versión 6 o superior), Firefox y Chrome (versiones respaldadas por sus respectivos fabricantes). 4. client (4C): Este debe estar instalado en la máquina del usuario. Se debe utilizar la versión de demo que se encuentra en la siguiente URL: demo_v1.0.zip Requisitos y preparación del escenario de pruebas 7

8 NOTA: Si se desea únicamente realizar pruebas de firma digital se puede acceder con credenciales a través de: Usuario: user2 Contraseña: passwd2 Descripción técnica para el desarrollo Para la realización del proceso de firma, hay que tener en cuenta que: Que el archivo a firmar esté previamente generado. 4C permite firmar tanto documentos que se hallen en local como en el cloud, accesibles mediante una url. El documento firmado se almacena en una carpeta temporal y se sube al servidor a través de FILES. Cuando la carga se ha completado, el AS debe responder con un redireccionamiento. sign.php <!DOCTYPE html> <html> <script> function setcookie(c_name,value,exdays) { var exdate=new Date(); exdate.setdate(exdate.getdate() + exdays); var c_value=escape(value) + ((exdays==null)? "" : "; expires="+exdate.toutcstring()); document.cookie=c_name + "=" + c_value; } setcookie('bit4id-sign','sign',1) </script> <head> <meta charset="utf-8" /> <title>firma Digital de un Documento en una URL</title> </head> <body> <?php $folders="demos_/firmar_un_doc_online/"; $url=" $documentname="documento_online"; $documentid="_01_online"; $tipo="pades"; $url server_sign=" <form class="bit4id-sign" method="post" action="demos_/firmar_un_doc_online/sign-ok.php"> <div class="bit4id-signreq" > <div class="bit4id-document"> Documento_a_firmar01.pdf</div> <div class="bit4id-documentname"> documento_online </div> <div class="bit4id-documentid">_01_online</div> <div class="bit4id-signaturetype">pades</div> </div> <div id="bit4id-status">loading</div> Descripción técnica para el desarrollo 8

9 <input type="submit" disabled="disabled" value="firmar" /> </form> <script src=" </body> </html> El nombre sign.php es, obviamente, personalizable (también su contenido). Sin embargo, es necesario tener, en la página: Un formulario de clase bit4id-sign con el atributo de acción que apunta a la url que recibirá el documento firmado digitalmente (que en este caso, por ejemplo, se llama "sign-ok.php") El formulario debe descender directamente del div de clase id bit4id-document. Este div contiene las url relativas/absolutas desde las cuales descargar los archivos para firmar. Como resultado del formulario form con id bit4id-sign el div que contiene el firmante que hay que colocar debe presentarse (en el ejemplo es un tipo de firma PAdES. Durante todo el proceso de la firma del div de clase: bit4id-status se actualiza constantemente por la 4C con el estado actual. Por ejemplo, "conectando", "conectado", "error: Descripción del error", etc Inmediatamente antes de la etiqueta de cierre </ body> debe haber una etiqueta <script> que cargará el código javascript 4S necesario para la automatización de la página. También se proporciona, de forma automática, a través del esquema name2 del propietario registrado en la instalación 4C, la capacidad de comunicarse al 4C la información necesaria para construir un canal de comunicación criptográfico seguro a través de 4S. Una vez que el canal se construye, el 4C lo utiliza para encontrar las órdenes de la 4S a través de una solicitud3 de larga duración. El código de javascript cargado construye un canal de comunicación 4C 4S WB. El código de javascript bit4id-sign.min.js se suministra, entonces, automáticamente, a través de un esquema-nombre propietario registrado en la instalación del 4C, para comunicar la información necesaria al 4C para la construcción de un canal de comunicación criptográfica seguro a través de 4S. Una vez el canal 4C se ha creado se usa para encontrar las órdenes a través de 4S a través de una solicitud de larga duración. El 4C descarga el documento de la URL actual en el div de clase bit4id-document, se mostrará al usuario (el documento no se muestra en el AW y el usuario es el que asegura que lo que debe firmar) y recogerá su consentimiento para la firma solicitando el PIN. Una vez que el archivo se ha recibido, el AS responderá a 4C con una redirección HTTP (por ejemplo, un 302 Found4). El 4C transferirá la solicitud de redirección al navegador web. El AS lo puede recibir con una estructura de este estilo (sign-ok.php): Descripción técnica para el desarrollo 9

10 sign-ok.php <?php //$_FILE["attach"]=Información del documento firmado. //$_POST["documentID"]=Identificador que hemos marcado en index.php. if (!empty($_files["attach"])) { $myfile = $_FILES["attach"]; if ($myfile["error"]!== UPLOAD_ERR_OK) { echo "<p>ha ocurrido un error en la subida del fichero.</p>"; exit; } $name = preg_replace("/[^a-z0-9._-]/i", "_", $myfile["name"]); } else { }?> $parts = pathinfo($name); $name=$parts["filename"]."-".$_post["documentid"].".".$parts["extension"]; /* Aquí se puede indicar donde guardar el documento firmado. Tal y como está configurado se guardará en la misma carpeta donde estan los PHP. */ $success = move_uploaded_file($myfile["tmp_name"],$name); if (!$success) { echo "<p>no puede guardar el archivo.</p>"; exit; } header("location: sign-end-ok.php?file=".$name); /* Redireción del navegador */ exit(); header("location: sign-end-error.php"); /* Redireción del navegador */ exit(); En la página de redirección se puede descargar el documento firmado. Tan solo es necesario llamar a la variable que almacena la ruta del documento. sign-end-ok.php <html> <p> Su documento ha sido firmado correctamente</p> </html> <a href="<?php echo $_GET['file'];?> /> Pulse aquí para descargarlo </a> Descripción técnica para el desarrollo 10