Source code: hk/hku/cecid/phoenix/pki/XMLDSigner.java
1 /*
2 * Academic Free License
3 * Version 1.0
4 *
5 * This Academic Free License applies to any software and associated
6 * documentation (the "Software") whose owner (the "Licensor") has placed the
7 * statement "Licensed under the Academic Free License Version 1.0" immediately
8 * after the copyright notice that applies to the Software.
9 *
10 * Permission is hereby granted, free of charge, to any person obtaining a copy
11 * of the Software (1) to use, copy, modify, merge, publish, perform,
12 * distribute, sublicense, and/or sell copies of the Software, and to permit
13 * persons to whom the Software is furnished to do so, and (2) under patent
14 * claims owned or controlled by the Licensor that are embodied in the Software
15 * as furnished by the Licensor, to make, use, sell and offer for sale the
16 * Software and derivative works thereof, subject to the following conditions:
17 *
18 * - Redistributions of the Software in source code form must retain all
19 * copyright notices in the Software as furnished by the Licensor, this list
20 * of conditions, and the following disclaimers.
21 * - Redistributions of the Software in executable form must reproduce all
22 * copyright notices in the Software as furnished by the Licensor, this list
23 * of conditions, and the following disclaimers in the documentation and/or
24 * other materials provided with the distribution.
25 * - Neither the names of Licensor, nor the names of any contributors to the
26 * Software, nor any of their trademarks or service marks, may be used to
27 * endorse or promote products derived from this Software without express
28 * prior written permission of the Licensor.
29 *
30 * DISCLAIMERS: LICENSOR WARRANTS THAT THE COPYRIGHT IN AND TO THE SOFTWARE IS
31 * OWNED BY THE LICENSOR OR THAT THE SOFTWARE IS DISTRIBUTED BY LICENSOR UNDER
32 * A VALID CURRENT LICENSE. EXCEPT AS EXPRESSLY STATED IN THE IMMEDIATELY
33 * PRECEDING SENTENCE, THE SOFTWARE IS PROVIDED BY THE LICENSOR, CONTRIBUTORS
34 * AND COPYRIGHT OWNERS "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
35 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
36 * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
37 * LICENSOR, CONTRIBUTORS OR COPYRIGHT OWNERS BE LIABLE FOR ANY CLAIM, DAMAGES
38 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
39 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE.
40 *
41 * This license is Copyright (C) 2002 Lawrence E. Rosen. All rights reserved.
42 * Permission is hereby granted to copy and distribute this license without
43 * modification. This license may not be modified without the express written
44 * permission of its copyright owner.
45 */
46
47 /* =====
48 *
49 * $Header: /ebxml/staff/cecid/cvs_repository/pki/src/hk/hku/cecid/phoenix/pki/XMLDSigner.java,v 1.3 2002/12/13 03:59:14 kcyee Exp $
50 *
51 * Code authored by:
52 *
53 * kcyee [2002-05-16]
54 *
55 * Code reviewed by:
56 *
57 * username [YYYY-MM-DD]
58 *
59 * Remarks:
60 *
61 * =====
62 */
63
64 package hk.hku.cecid.phoenix.pki;
65
66 import java.io.InputStream;
67 import org.w3c.dom.Document;
68 import org.w3c.dom.Element;
69
70 /**
71 * This interface defines a standard way to have the document signed.
72 * Different classes will implement the interface using different
73 * library behind.
74 *
75 * @author kcyee
76 * @version $Revision: 1.3 $
77 */
78 public interface XMLDSigner {
79
80 /**
81 * Set the envelope to host the Signature element. That is the
82 * XML document where the Signature element to be added. The
83 * digital signature here will always be an enveloped signature.
84 * The envelope will be included in the process of signing.
85 *
86 * @param doc the XML document to host the Signature element
87 * @throws SignException
88 */
89 public void setEnvelope(Document doc) throws SignException;
90
91 /**
92 * Adds a reference to a document attachment to the signature.
93 *
94 * @param uri the URI of the document attachment
95 * @param is the input stream of the content of the document
96 * @param contentType the content type of the document
97 */
98 public void addDocument(String uri, InputStream is, String contentType);
99
100 /**
101 * Signs the envelope and documents by using the specified key
102 * in the keystore.
103 *
104 * @param ks the keystore holding the key for signing
105 * @param alias the alias of the key for signing
106 * @param password the password for accessing the key for signing
107 * @throws SignException when there is any error in the processing of
108 * signing
109 */
110 public void sign(CompositeKeyStore ks, String alias, char[] password)
111 throws SignException;
112
113 /**
114 * Sets the trust anchor for verfication of certificate path.
115 *
116 * @param ks the keystore providing the trusted certificates
117 */
118 public void setTrustAnchor(CompositeKeyStore ks);
119
120 /**
121 * Verifies the signature in the envelope passed in, which may reference
122 * the documents specified using the addDocument method.
123 *
124 * @return true if the signature can be verified successfully, false
125 * if otherwise.
126 * @throws VerifyException when there is any error in the processing of
127 * verification
128 */
129 public boolean verify() throws VerifyException;
130
131 /**
132 * Gets the DOM element of the signature generated.
133 *
134 * @return the DOM element of the signature
135 */
136 public Element getElement();
137 }