1
2 package es.caib.signatura.api;
3
4
5 import java.io.InputStream;
6 import java.io.FileNotFoundException;
7 import java.io.IOException;
8 import java.io.OutputStream;
9 import java.security.UnrecoverableKeyException;
10 import java.security.cert.X509Certificate;
11 import java.util.Date;
12 import java.net.*;
13
14 /**
15 * Interface to abstract signing and verifying implementations of diferent certificate entities. Generated
16 * signatures are detached (doesn't include signed data) and can have timestamp.
17 * Signatures are encapsulated into <code>Signature</code> objects.
18 *
19 * @author Jesús Reyes (3dígits)
20 * @version 1.0
21 * @see Signature
22 */
23 public interface Signer {
24
25 /**
26 * Indicates that the signature will be added in the upper part of the PDF document.
27 */
28 static final int PDF_SIGN_POSITION_TOP = 1;
29
30 /**
31 * Indicates that the signature will be added in the bottom part of the PDF document.
32 */
33 static final int PDF_SIGN_POSITION_BOTTOM = 2;
34
35 /**
36 * Indicates that the signature will be added in the left part of the PDF document.
37 */
38 static final int PDF_SIGN_POSITION_LEFT = 4;
39
40 /**
41 * Indicates that the signature will be added int the right part of the PDF document.
42 */
43 static final int PDF_SIGN_POSITION_RIGHT = 8;
44
45 /**
46 * Neither code bars nor signer information will be added to the PDF document.
47 */
48 static final int PDF_SIGN_POSITION_NONE = 0;
49 /**
50 * Indica que sólo se añadirá en la última página
51 */
52 static final int PDF_SIGN_PAGE_LAST = 16;
53 /**
54 * Indica que se añadirá una estampa por defecto de adobe, en vez del código de puntos PDF417.
55 */
56 static final int PDF_SIGN_DEFAULT_SIGNATURE_APPERANCE = 32;
57
58 static final int PDF_SIGN_PDF417_SIGNATURE_APPERANCE = 64;
59
60
61 /**
62 * Gets the available certificate names list to the API: hard disk, USB devices, cryptographic cards, etc.
63 *
64 * @return the names of the available certificates.
65 * @throws SignatureCertNotFoundException if no available certificates.
66 * @throws SignaturePrivKeyException if unable to access to private keys.
67 */
68 public String[] getCertList(String contentType) throws SignatureCertNotFoundException, SignaturePrivKeyException;
69
70 /**
71 * Gets the digital signature of a hard disk document and encapsulates it into a signature object without timestamp.
72 *
73 * @param fileName path of the document.
74 * @param certificateName name of the certificate used to sign the document.
75 * @param password private key password of the certificate.
76 * @param contentType MIME type of the document to sign.
77 * @return {@link Signature} the document signature.
78 * @throws FileNotFoundException if unable to find the document.
79 * @throws IOException if I/O errors occurs.
80 * @throws SignatureProviderException if unable to access to the signature API needed provider.
81 * @throws SignatureSignException if an error occurs at signing process.
82 * @throws UnrecoverableKeyException if the private key password is not correct.
83 * @throws SignatureException if any signature error occurs.
84 */
85 public Signature sign (String fileName, String certificateName, String password, String contentType)
86 throws IOException, SignatureException;
87
88 /**
89 * Gets the digital signature of an input data stream and encapusulates it into a <code>Signature</code> object
90 * without timestamp.
91
92 * @param contentStream data stream to sign.
93 * @param certificateName certificate name to use.
94 * @param password private key password of the certificate to use.
95 * @param contentType MIME type of the document to sign.
96 * @return {@link Signature} the signature of the data stream.
97 * @throws IOException if I/O errors occurs.
98 * @throws SignatureProviderException if unable to access to the signature API needed provider.
99 * @throws SignatureSignException if an error occurs at signing process.
100 * @throws UnrecoverableKeyException if the private key password is not correct.
101 * @throws SignatureException if any signature error occurs.
102 */
103 public Signature sign (InputStream contentStream, String certificateName, String password, String contentType)
104 throws IOException, SignatureException;
105
106 /**
107 * Signs a document obtained from an URL.
108 *
109 * @param url URL address where is located the document to sign.
110 * @param certificateName certificate name to use.
111 * @param password private key password of the certificate to use.
112 * @param contentType MIME type of the document to sign.
113 * @return {@link Signature} the signature of the document.
114 * @throws FileNotFoundException if original file not found.
115 * @throws IOException if I/O errors occurs.
116 * @throws SignatureProviderException if unable to access to the signature API needed provider.
117 * @throws SignatureSignException if an error occurs at signing process.
118 * @throws UnrecoverableKeyException if the private key password is not correct.
119 * @throws SignatureException if any signature error occurs.
120 */
121
122 public void signPDF (InputStream contentStream, OutputStream signedStream, String certificateName,
123 String password, String contentType, String url, int position)
124 throws IOException, SignatureException;
125
126 /**
127 * Signs a PDF document. In one of the borders of the document
128 * appears the signer's certificate name, an URL where the PDF document can be downloaded and a bar code in PDF417 format
129 * that codifies the url.
130 *
131 * @param contentStream data stream to sign.
132 * @param signedStream resulting signed data stream.
133 * @param certificateName certificate name to use.
134 * @param password private key password of the certificate to use.
135 * @param contentType MIME type of the document to sign.
136 * @param url URL to add to the document.
137 * @param position Position in each page of the document where the URL will be added. The possible values are:
138 * PDF_SIGN_POSITION_TOP, PDF_SIGN_POSITION_BOTTOM, PDF_SIGN_POSITION_RIGHT o PDF_SIGN_POSITION_LEFT.
139 * @param allowMultipleSignature allow to sign an already signed PDF
140 *
141 * @return the signed PDF document.
142 * @throws IOException if I/O errors occurs.
143 * @throws SignatureProviderException if unable to access to the signature API needed provider.
144 * @throws SignatureSignException if an error occurs at signing process.
145 * @throws UnrecoverableKeyException if the private key password is not correct.
146 * @throws SignatureException if any signature error occurs.
147 */
148 public void signPDF (InputStream contentStream, OutputStream signedStream, String certificateName,
149 String password, String contentType, String url, int position, boolean allowMultipleSignature)
150 throws IOException, SignatureException;
151
152 /**
153 * Signs a PDF document and returns the signed PDF document. In one of the borders of the document
154 * appears the signer's certificate name, an URL where the PDF document can be downloaded and a bar code in PDF417 format
155 * that codifies the url.
156 *
157 * @param contentStream data stream to sign.
158 * @param certificateName certificate name to use.
159 * @param password private key password of the certificate to use.
160 * @param contentType MIME type of the document to sign.
161 * @param url URL to add to the document.
162 * @param position Position in each page of the document where the URL will be added. The possible values are:
163 * PDF_SIGN_POSITION_TOP, PDF_SIGN_POSITION_BOTTOM, PDF_SIGN_POSITION_RIGHT o PDF_SIGN_POSITION_LEFT.
164 *
165 * @return the signed PDF document.
166 * @throws IOException if I/O errors occurs.
167 * @throws SignatureProviderException if unable to access to the signature API needed provider.
168 * @throws SignatureSignException if an error occurs at signing process.
169 * @throws UnrecoverableKeyException if the private key password is not correct.
170 * @throws SignatureException if any signature error occurs.
171 *
172 * @deprecated
173 */
174
175 public OutputStream signPDF (InputStream contentStream, String certificateName, String password,
176 String contentType, String url, int position)
177 throws IOException, SignatureException;
178
179 /**
180 * Signs a PDF document and returns the signed PDF document. In one of the borders of the document
181 * appears the signer's certificate name, an URL where the PDF document can be downloaded and a bar code in PDF417 format
182 * that codifies the url.
183 *
184 * @param contentStream data stream to sign.
185 * @param certificateName certificate name to use.
186 * @param password private key password of the certificate to use.
187 * @param contentType MIME type of the document to sign.
188 * @param url URL to add to the document.
189 * @param position Position in each page of the document where the URL will be added. The possible values are:
190 * PDF_SIGN_POSITION_TOP, PDF_SIGN_POSITION_BOTTOM, PDF_SIGN_POSITION_RIGHT o PDF_SIGN_POSITION_LEFT.
191 * @param allowMultipleSignature allow to sign an already signed PDF
192 *
193 * @return the signed PDF document.
194 * @throws IOException if I/O errors occurs.
195 * @throws SignatureProviderException if unable to access to the signature API needed provider.
196 * @throws SignatureSignException if an error occurs at signing process.
197 * @throws UnrecoverableKeyException if the private key password is not correct.
198 * @throws SignatureException if any signature error occurs.
199 *
200 * @deprecated
201 */
202
203 public OutputStream signPDF (InputStream contentStream, String certificateName, String password,
204 String contentType, String url, int position, boolean allowMultipleSignature)
205 throws IOException, SignatureException;
206
207 /**
208 * Firma digitalmente de un documento PDF pasado como <code>InputStream</code> y devuelve el mismo PDF firmado
209 * y modificado. Las opciones de firma PDF estan establecidas en la clase <code>Signer</code>.
210 *
211 * @param pdfInputStream
212 * @param signedStream
213 * @param certificateName Nombre del certificado obtenido de la llamada a Signer.getCertList()
214 * @param password contraseña de la clave privada del usuario
215 * @param contentType tipo MIME del documento a firmar
216 * @param textoAdicional URL en caso de estampado PDF417, o motivo de firma para firmas con estampado ABODE
217 * @param stampOptions Opciones de firma PDF definidas en la clase <code>Signer</code>
218 * @param top El 0 corresponde al borde inferior del documento.
219 * @param left El 0 corresponde al borde izquierdo del documento
220 * @param height Anchura máxima de la estampa, el texto de dividirà en las líneas necesarias para que quepa en la anchura establecida.
221 * @param width Altura máxima de la estampa. Debe tenerse en cuenta que si la altura no es suficientemente grande para el texto que se divide en múltiples líneas, este se corta y desaparece.
222 * @param rotation Sólo permite rotación la firma con estampado PDF417. En caso de rotación el estampado se rotarà desde la esquina inferior izquierda (top, left).
223 * @param allowMultipleSignature Permitir o no refirmado del documento PDF si el documento de entrada ya está firmado
224 * @throws IOException
225 * @throws SignatureException
226 */
227 public void signPDF(InputStream pdfInputStream, OutputStream signedStream,
228 String certificateName,String password, String contentType,
229 String textoAdicional, int stampOptions,
230 float top, float left,float height, float width, float rotation,
231 boolean allowMultipleSignature) throws IOException, SignatureException;
232
233
234 /**
235 * Firma digitalmente de un documento PDF pasado como <code>InputStream</code> y devuelve el mismo PDF firmado
236 * y modificado de forma que, en uno de los bordes del documento que se le indique, aparezca el firmante que
237 * compulsa la copia, la url desde la que se puede consultar el PDF y una matriz de puntos en formato PDF417 que
238 * continene esa misma URL.
239 * @param contentStream
240 * @param signedStream
241 * @param certificateName
242 * @param password
243 * @param contentType
244 * @param url
245 * @param localidad
246 * @param x
247 * @param y
248 * @param rotation
249 * @throws IOException
250 * @throws SignatureException
251 */
252 public void certifyDigitalCopy (InputStream contentStream, OutputStream signedStream, String certificateName,
253 String password, String contentType, String url, String localidad, float x, float y, float rotation)
254 throws IOException, SignatureException;
255
256 /**
257 * Signs a document obtained from an URL.
258 *
259 * @param url URL address where is located the document to sign.
260 * @param certificateName certificate name to use.
261 * @param password private key password of the certificate to use.
262 * @param contentType MIME type of the document to sign.
263 * @return {@link Signature} the signature of the document.
264 * @throws FileNotFoundException if original file not found.
265 * @throws IOException if I/O errors occurs.
266 * @throws SignatureProviderException if unable to access to the signature API needed provider.
267 * @throws SignatureSignException if an error occurs at signing process.
268 * @throws UnrecoverableKeyException if the private key password is not correct.
269 * @throws SignatureException if any signature error occurs.
270 */
271 public Signature sign (URL url, String certificateName, String password, String contentType)
272 throws IOException, SignatureException;
273
274 /**
275 * Verifies the signature of an input data stream. If the digital signature requires a timestamp
276 * and don't have it then a timestamp is added (if possible).
277 *
278 * @param contentStream data stream of the original document.
279 * @param signatureData signature to verify.
280 * @return <code>true</code> if the verification is correct; <code>false</code> otherwise.
281 * @throws SignatureProviderException if unable to access to the signature API needed provider.
282 * @throws IOException if the document or the timestamp server is not available.
283 * @throws SignatureVerifyException if an error occurs at verifying process.
284 */
285 public boolean verifyAPosterioriTimeStamp(InputStream contentStream, Signature signatureData)
286 throws SignatureProviderException, IOException, SignatureVerifyException;
287
288 /**
289 * Verifies the digital signature of a document obtained from an URL. If the digital signature requires a timestamp
290 * and don't have it then a timestamp is added (if possible).
291 *
292 * @param url URL of the original document.
293 * @param signatureData signature to verify.
294 * @return <code>true</code> if the verification is correct; <code>false</code> otherwise.
295 * @throws SignatureProviderException if unable to access to the signature API needed provider.
296 * @throws IOException if the document or the timestamp server is not available.
297 * @throws SignatureVerifyException if an error occurs at verifying process.
298 */
299 public boolean verifyAPosterioriTimeStamp(URL url, Signature signatureData)
300 throws SignatureProviderException, IOException, SignatureVerifyException;
301
302 /**
303 * Verifies the digital signature of an input data stream. If the digital signature requires a timestamp
304 * and don't have it then a timestamp is added (if possible).
305 *
306 * @param fileName path of the original document.
307 * @param signatureData signature to verify.
308 * @return <code>true</code> if the verification is correct; <code>false</code> otherwise.
309 * @throws SignatureProviderException if unable to access to the signature API needed provider.
310 * @throws IOException if the document or the timestamp server is not available.
311 * @throws SignatureVerifyException if an error occurs at verifying process.
312 */
313 public boolean verifyAPosterioriTimeStamp(String fileName, Signature signatureData)
314 throws SignatureProviderException, IOException, SignatureVerifyException;
315
316 /**
317 * Verifies the digital signature of a document obtained from an URL. If the digital signature requires a timestamp
318 * and don't have it then a timestamp is added (if possible).
319 *
320 * @param url URL address where is located the original document.
321 * @param signatureData signature to verify.
322 * @return <code>true</code> if the verification is correct; <code>false</code> otherwise.
323 * @throws SignatureProviderException if unable to access to the signature API needed provider.
324 * @throws IOException if the document or the timestamp server is not available.
325 * @throws SignatureVerifyException if an error occurs at verifying process.
326 */
327 public boolean verify(InputStream contentStream, Signature signatureData)
328 throws SignatureProviderException, IOException, SignatureVerifyException;
329
330 /**
331 * Verifies the digital signature of a document contained into the hard disk.
332 * If the digital signature requires a timestamp and don't have it then a timestamp is added (if possible).
333 *
334 * @param fileName path of the original document.
335 * @param signatureData signature to verify.
336 * @return <code>true</code> if the verification is correct; <code>false</code> otherwise.
337 * @throws FileNotFoundException if original file not found.
338 * @throws SignatureProviderException if unable to access to the signature API needed provider.
339 * @throws IOException if the document or the timestamp server is not available.
340 * @throws SignatureVerifyException if an error occurs at verifying process.
341 */
342 public boolean verify(String fileName, Signature signatureData) throws
343 FileNotFoundException, SignatureProviderException, IOException, SignatureVerifyException;
344
345
346 /**
347 * Verifies the digital signature of a document obtained from an URL.
348 * The verification process is independent of signature timestamp.
349 *
350 * @param url URL address where is located the original document.
351 * @param signatureData signature to verify.
352 * @return <code>true</code> if the verification is correct; <code>false</code> otherwise.
353 * @throws FileNotFoundException if original file not found.
354 * @throws SignatureProviderException if unable to access to the signature API needed provider.
355 * @throws IOException if the document or the timestamp server is not available.
356 * @throws SignatureVerifyException if an error occurs at verifying process.
357 */
358 public boolean verify(URL url, Signature signatureData) throws
359 SignatureProviderException, IOException, SignatureVerifyException;
360
361 /**
362 * Generates SMIME document from the document and its digital signature.
363 *
364 * @throws IOException if I/O errors occurs.
365 * @param smime output stream to write the generated SMIME document.
366 * @param signature digital signature of the document.
367 * @param document input stream of the original document.
368 */
369 public void generateSMIME (InputStream document, Signature signature, OutputStream smime) throws IOException;
370
371
372
373 /**
374 * Obtiene el documento SMIME a partir del documento original y el conjunto de firmas digitales obtenidas de firmas el documento.
375 * @param document InputStream con el documento que se firmó
376 * @param signatures firmas digital del documento
377 * @param smime OutputStream con el SMIME obtenido
378 * @throws IOException
379 */
380 public void generateSMIMEParalell(InputStream document, Signature[] signatures, OutputStream smime) throws IOException, SignatureException;
381
382 /**
383 * Obtiene la hora oficial que tendría un sello de tiempo generado en ese mismo instante
384 *
385 * @return Hora Oficial
386 * @param certificateName nombre del certificado que se usará para firmar
387 * @param password contraseña de la clave privada del usuario
388 * @param contentType tipo MIME del documento a firmar
389 * @throws IOException
390 * @throws SignatureException
391 */
392 public Date getCurrentDate(String certificateName, String password, String contentType) throws SignatureTimestampException, SignatureException, IOException;
393
394 /**
395 * Gets the API version number.
396 *
397 * @return the API version number;
398 */
399 public String getAPIVersion();
400
401
402 /**
403 * Returns an SMIMEParser object to access to the SMIME document information.
404 *
405 * @param smime the SMIME document to read.
406 * @return an SMIMEParser object to access to the SMIME document information.
407 * @throws FileNotFoundException if smime file not found.
408 * @throws InstantiationException if problems instanciating the SMIMEParserObject.
409 * @throws IllegalAccessException if problems instanciating the SMIMEParserObject.
410 * @throws IOException if I/O errors occurs.
411 * @throws SignatureException if any signature error occurs.
412 */
413
414 public SMIMEParser getSMIMEParser(InputStream smime) throws FileNotFoundException, InstantiationException, IllegalAccessException, IOException, SignatureException;
415
416 /**
417 * Returns basic certificate information.
418 *
419 * @param certificate Certificat to parse.
420 * @return Parsed certificate.
421 */
422 public ParsedCertificate parseCertificate(X509Certificate certificateChain);
423
424 }