4identity JAVA Integration Guide (Signature)

4identity
JAVA Integration Guide (Signature)
Bit4id Ibérica
C/ Marie Curie, 8-14
Forum Nord de Tecnología
08042 – Barcelona
España
Tel. +34 935 35 35 18
[email protected]
Bit4id Italia
Via Coroglio, 57
Città della Scienza
80124 Napoli
Italia
Tel. +39 081 762 56 00
[email protected]
Bit4id UK
2 London Wall Buildings
London Wall,
London EC2M 5UU
United Kingdom
Tel. +44 (0) 203 397 3166
[email protected]
Oficina Lisboa
Rua Cesário Verde, 32
2790-495 Queijas (Lisboa)
Portugal
Tel .+351 914 58 30 21
[email protected]
Oficina Milán
Corso Vercelli, 11
20144 Milano
Italia
Tel. +39 024 547 42 59
[email protected]
Oficina Guatemala
15 avenida, 14-09 zona 10
Oakland - 01010
Guatemala
Guatemala
Tel: +502 22 21 91 63
[email protected]
Bit4id Perú
Avda. Olavegoya, nº 1835
Distrito Jesus Maria
Lima 11
Perú
Tel: +51 947 744 704
[email protected]
ISO 9001:2008
ISO 14001:2004
ISO 27001:2005
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
Summary
Summary ............................................................................................................................................... 2
Reviews ................................................................................................................................................. 3
Overview ............................................................................................................................................... 4
The integration ...................................................................................................................................... 4
Signature Process .............................................................................................................................. 5
Java code ....................................................................................................................................... 6
Summary
Signature Parameter ........................................................................................................................... 10
2
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
Revisión
Fechas
Cambio
Autor
1.0
10/01/2013
Primera redacción
CSC - CBU
1.1
02/04/2014
Revisión técnica
JGM
1.2
04/04/2014
Actualización script
JGM
Reviews
Reviews
3
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
Overview
The main purpose of this document is to explain the manner to integrate the 4Identity system into
a generic customer scenario.
The generic customer scenario is composed of an:

Application server that host an application able to browse a generic PDF file and run
the signature against the 4Identity. It was chosen a PDF file due that after the file
signature this can be tested using a normal pdf reader.

Web Server that host the 4Identity server components called SMARTENGINE. This
component mainly manages the channel built between the 4Identity Client and the
browser. Moreover, the SMARTENGINE is also an active part on the Authentication
functionality while for the signature process is responsible only of the channel lifecycle.

User’s desktop client that host the 4Identity Client and run the web browser used to
access the web application hosted into the application server.
Figura 1 – Use case
The custom code shown in the following paragraphs has the main objective to drive the developer
for the main 4identity functionalities of Signature and Authentication. This custom code is only an
example like a “How To Use” 4Identity functionalities and so it is not a programming best practice.
The integration between the 4Identity technology and the customer web application means only
insert some custom tags.
Overview
The integration
4
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
In the following paragraphs will be shown the signature process on its functional architecture and
also the custom code needed for its integration.
Signature Process
The main components involved for the signature process are the application server that run the
code that manage the signed file and the 4identity client that sign the file. The main functionality of
the SMARTENGINE in this process is to maintain the channel lifecycle.
Detailing this process, the application stored on the application server is able to choose the file to
sign and to receive the signed file by a POST message from the 4Identity client. The application then
stores the signed file on a server.
Figura 2 – Signature Process
In the signature process the 4identity client installed on the client machine is able to show the user
the certificate to use for the signature:
Figura 3 – Choose the certificate for the signature
The integration
Show a preview of the document to sign:
5
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
Figura 4 – Document preview
and run the signature functionality. In the case of the document type is not PDF the following
window is shown to the user asking a proof for the the document review. After this check the sign
button is enabled and the document can be signed.
Figura 5 – Run the signature
Due that the 4Identity client do not need any custom code we will show the code for the
application run on application server.
This application is composed of:
1. a FORM to enable the user to choose a file to sign;
3. a landing page that give the result to the user and the link for the signed file.
Java code
For an environment using J2EE we will use:
The integration
2. a component to read the signed file sent by a post message and redirect he user to the
landing page;
6
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
a) an application server as.example.com:8080 that expose the custom application on
/4identity ;
b) the custom application 4identity consist of:

index.html: containing the form ;

a servlet called Signing that read the POST data and redirect the session to a
landing page called success.jsp;

a JSP page called success.jsp that show the user the signed file;
INDEX.HTML
See below the code for index.html page.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
<div>
<form class="bit4id-sign" action="4identity/Signing" method="post">
<p></p>
<div class="bit4id-signReq" style="display: none;">
<div class="bit4iddocument">http://as.example.com:8080/4identity/TestData.pdf</div>
<div class="bit4id-documentName">TEST PDF DOCUMENT</div>
<div class="bit4id-signatureType">PAdES</div>
<div class="bit4id-signingAlgorithm">RSASHA256</div>
<div class="bit4id-certInfo">CN</div>
</div>
<div>
<fieldset>
<div><h3>Document Signature</h3></div>
<div><p><strong>Proceeding the document TestData.pdf will be signed, are you
sure?</strong></p></div>
<div id="bit4id-status"></div>
<div><input type="submit" value="Sign Document" name="cmd" disabled></div>
</fieldset>
</div>
</form>
<script src="http://as-demo.bit4id.org/smartengine/bit4id-sign.min.js"></script>
</div>
This page contain the FORM element with the custom class bit4id-sign, the action configured
against our servlet Signing and the method set to POST:
<form class="bit4id-sign" action="4identity/Signing" method="post">
</form>
Then we need to build the signature request with the class bit4id-signReq. The request is filled with
the information for:
The integration
OTHER CODE HERE
7
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity

The document path, in this case is a file (TestData.pdf) stored on the server
as.example.com :
<div class="bit4id-document">http://as.example.com:8080/4identity/TestData.pdf</div>

The file name:
<div class="bit4id-documentName">TestData.pdf</div>

The signature Type (Pades):
<div class="bit4id-signatureType">PAdES</div>

The signature Algorithm (RSASHA256) :
<div class="bit4id-signingAlgorithm">RSASHA256</div>

The certificate’s attribute (CN) shown on the 4identity client:
<div class="bit4id-certInfo">CN</div>

The channel status information, used normally for debug purpose:
<div id="bit4id-status"></div>

The submit button to send the post, the name need to be cmd and disabled:
<div><input type="submit" value="Sign Document" name="cmd" disabled></div>

The script resource on the SMARTENGINE server deployed on the server
fe.example.com on the port 8082 :
<script src="http://as-demo.bit4id.org/smartengine/bit4id-sign.min.js"></script>
For the other information about the signature request see the chapter 0.
Signing servlet
See below the code for the Servlet class:
package com.bit4id.identity;
import
import
import
import
javax.servlet.ServletException;
javax.servlet.annotation.WebServlet;
javax.servlet.annotation.MultipartConfig;
javax.servlet.http.HttpServlet;
The integration
import java.io.IOException;
import java.io.File;
import java.io.PrintWriter;
8
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.Part;
@WebServlet("/Signing")
@MultipartConfig(fileSizeThreshold=1024*1024*10,maxFileSize=1024*1024*15,maxReque
stSize=1024*1024*30)
public class Signing extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final String contentdir = "D:\\jboss-as7.1.1\\standalone\\deployments\\4identity.war\\signed";
public Signing() {
super();
}
protected void doGet(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
PrintWriter out = response.getWriter();
out.println("SIGNATURE MANAGEMENT SERVLET");
out.close();
}
protected void doPost(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
String signstore ="http://as.example.com:8080/4identity/signed";
for (Part part : request.getParts()) {
part.write(contentdir + File.separator + "FILESIGNED.pdf");
}
response.sendRedirect("success.jsp?link=" + signstore + "//" +
"FILESIGNED.pdf");
}
}
As shown above is a Servlet standard that manage a POST message and store the file using the
annotation.
The main code is the read of the file in the POST message and save the signed file (FILESIGNED.pdf)
in the path written in the variable contentdir with :
After this, the code redirect the session to the landing page sending the link to download the file:
response.sendRedirect("success.jsp?link=" + signstore + "//" + "FILESIGNED.pdf");
The integration
for (Part part : request.getParts()) {
part.write(contentdir + File.separator + "FILESIGNED.pdf");
}
9
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
success.jsp
See below the code for page success.jsp:
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Signature Process</title>
</head>
<body>
<% String link = request.getParameter( "link" ); %>
The signature process is ended correctly. The signature file can be
dowloaded here: <a href=<%=link.toString()%>>SIGNED FILE</a>
</body>
</html>
The code above read the link sent :
<% String link = request.getParameter( "link" ); %>
And build the link for the file download:
<a href=<%=link.toString()%>>SIGNED FILE</a>
Signature Parameter
Below are detailed the parameter for the signature functionality.
CAdES SIGNATURE API
Parameter
Values
Default
bit4id-signatureType
“CAdES”
NO DEFAULT
bit4id-signingAlgorithm
“RSASHA256”, “RSASHA1”, “RSAMD5”
“RSASHA256”
bit4id-encoding
“1”, “0”
“0”
bit4id-issuerFilter
“CN=..., OU=..., T=..., ecc.”
“”
bit4id-certType
“ANY”, “SIG”, “AUT”
“ANY”
bit4id-certInfo
“CN, OU, T, ecc.”
NO DEFAULT
bit4id-signingAlgorithm: Defines the algorithm that will be used to sign.
Signature Parameter
This section describes the parameters of the signature to be included within the form class:
bit4idsignReq to perform a CAdES signature request.
10
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
bit4id-encoding: Defines the encoding of the output signed file. 1 for base64 encoding or 0 for
binary encoding.
bit4id-issuerFilter: Defines the signing certificate filter as a sub-string of the certificate issuer
distinguished name.
bit4id-certType: Defines the signing certificate filter as a string describing the type of certificate.
bit4id-certInfo: Defines the attribute shown on the 4Identity client.
PAdES SIGNATURE API
This section describes the parameters of the signature to be included within the form class:
bit4idsignReq to perform a PAdES signature request.
Parameter
Values
bit4id-signatureType
“PAdES”
Default
NO DEFAULT
“0” (Invisible)
bit4id-page
“0”, “1”..”n”
bit4id-position
“[1x, 1y, 2x, 2y]”
bit4id-location
“location string”
bit4id-reason
“reason string”
bit4id-signingAlgorithm
“RSASHA256”, “RSASHA1”, “RSAMD5”
bit4id-paragraphFormat
“signature string (on image)”
bit4id-image
“http://imageurl”,
“data:image/png;base64,R0lGODdhMA...”
“”
bit4id-issuerFilter
“CN=..., OU=..., T=..., .=...”
“”
bit4id-certType
“ANY”, “SIG”, “AUT”
“ANY”
bit4id-certInfo
“CN, OU, T, ecc.”
NO DEFAULT
“[]”
“”
“”
“RSASHA256”
“”
bit4id-page: Defines the pdf document page where the signature will be added. (Only for graphical
signature)
bit4id-position: Defines the position, in points, on the pdf document page selected, where the
signature will be shown. (Only for graphical signature)
bit4id-signingAlgorithm: Defines the algorithm that will be used to sign.
bit4id-paragraphFormat: Defines the text that will be drawn on the graphic signature.
bit4id-image: Defines the url or data-url from where to download the image that will be used for
the graphical signature appearance.
Signature Parameter
bit4id-location: Defines the location of signing.
11
Título documento:
04/04/2014
JAVA Integration Guide (Signature)
Versión 1.2
Producto:
4identity
bit4id-issuerFilter: Defines the signing certificate filter as a sub-string of the certificate issuer
distinguished name.
bit4id-certType: Defines the signing certificate filter as a string describing the type of certificate.
bit4id-certInfo: Defines the attribute shown on the 4Identity client.
XAdES SIGNATURE API
This section describes the parameters of the signature to be included within the form class:
bit4idsignReq to perform a XAdES signature request.
Parameter
Values
Default
bit4id-signatureType
“XADES”
NO DEFAULT
bit4id-hashAlgorithm
“SHA256”, “SHA1”, “MD5”
“SHA256”
bit4id-signatureMode
“Enveloping”, “Enveloped”, “InternalDetached”, “Binary”
“Enveloped”
bit4id-level
“BES”, “T”, “C”, “X”, “XL”
“BES”
bit4id-binary
“xpath of node to be signed”
“/*”
bit4id-xpath
“RSASHA256”, “RSASHA1”, “RSAMD5”
“RSASHA256”
bit4id-issuerFilter
“CN=..., OU=..., T=..., .=...”
bit4id-certType
“ANY”, “SIG”, “AUT”
“ANY”
bit4id-certInfo
“CN, OU, T, ecc.”
NO DEFAULT
“”
bit4id-hashAlgorithm: Defines the type of hashing algorithm that is used to sign.
bit4id-signatureMode: Defines the type of XAdES signature that will be used.
bit4id-level: Defines the level of XAdES signature that will be used.
bit4id-binary: Set to 1 if you want sign a binary file, or 0 to sign an xml.
bit4id-xpath: Defines the node of the XML document that will be signed as an xpath expression
string.
bit4id-issuerFilter: Defines the signing certificate filter as a sub-string of the certificate issuer
distinguished name.
bit4id-certType: Defines the signing certificate filter as a string describing the type of certificate.
bit4id-certInfo: Defines the attribute shown on the 4Identity client.
12