1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.ws.security.components.crypto;
20
21 import org.apache.ws.security.WSSecurityException;
22
23 import java.io.InputStream;
24 import java.security.PrivateKey;
25 import java.security.PublicKey;
26 import java.security.cert.CertificateFactory;
27 import java.security.cert.X509Certificate;
28
29 import javax.security.auth.callback.CallbackHandler;
30
31 public interface Crypto {
32
33 //
34 // Accessor methods
35 //
36
37 /**
38 * Get the crypto provider associated with this implementation
39 * @return the crypto provider
40 */
41 String getCryptoProvider();
42
43 /**
44 * Set the crypto provider associated with this implementation
45 * @param provider the crypto provider to set
46 */
47 void setCryptoProvider(String provider);
48
49 /**
50 * Retrieves the identifier name of the default certificate. This should be the certificate
51 * that is used for signature and encryption. This identifier corresponds to the certificate
52 * that should be used whenever KeyInfo is not present in a signed or an encrypted
53 * message. May return null. The identifier is implementation specific, e.g. it could be the
54 * KeyStore alias.
55 *
56 * @return name of the default X509 certificate.
57 */
58 String getDefaultX509Identifier() throws WSSecurityException;
59
60 /**
61 * Sets the identifier name of the default certificate. This should be the certificate
62 * that is used for signature and encryption. This identifier corresponds to the certificate
63 * that should be used whenever KeyInfo is not present in a signed or an encrypted
64 * message. The identifier is implementation specific, e.g. it could be the KeyStore alias.
65 *
66 * @param identifier name of the default X509 certificate.
67 */
68 void setDefaultX509Identifier(String identifier);
69
70 /**
71 * Sets the CertificateFactory instance on this Crypto instance
72 *
73 * @param provider the CertificateFactory provider name
74 * @param certFactory the CertificateFactory the CertificateFactory instance to set
75 */
76 void setCertificateFactory(String provider, CertificateFactory certFactory);
77
78 /**
79 * Get the CertificateFactory instance on this Crypto instance
80 *
81 * @return Returns a <code>CertificateFactory</code> to construct
82 * X509 certificates
83 * @throws org.apache.ws.security.WSSecurityException
84 */
85 CertificateFactory getCertificateFactory() throws WSSecurityException;
86
87 //
88 // Base Crypto functionality methods
89 //
90
91 /**
92 * Load a X509Certificate from the input stream.
93 *
94 * @param in The <code>InputStream</code> containing the X509 data
95 * @return An X509 certificate
96 * @throws WSSecurityException
97 */
98 X509Certificate loadCertificate(InputStream in) throws WSSecurityException;
99
100 /**
101 * Reads the SubjectKeyIdentifier information from the certificate.
102 * <p/>
103 * If the the certificate does not contain a SKI extension then
104 * try to compute the SKI according to RFC3280 using the
105 * SHA-1 hash value of the public key. The second method described
106 * in RFC3280 is not support. Also only RSA public keys are supported.
107 * If we cannot compute the SKI throw a WSSecurityException.
108 *
109 * @param cert The certificate to read SKI
110 * @return The byte array containing the binary SKI data
111 */
112 byte[] getSKIBytesFromCert(X509Certificate cert) throws WSSecurityException;
113
114 /**
115 * Get a byte array given an array of X509 certificates.
116 * <p/>
117 *
118 * @param certs The certificates to convert
119 * @return The byte array for the certificates
120 * @throws WSSecurityException
121 */
122 byte[] getBytesFromCertificates(X509Certificate[] certs) throws WSSecurityException;
123
124 /**
125 * Construct an array of X509Certificate's from the byte array.
126 *
127 * @param data The <code>byte</code> array containing the X509 data
128 * @return An array of X509 certificates
129 * @throws WSSecurityException
130 */
131 X509Certificate[] getCertificatesFromBytes(byte[] data) throws WSSecurityException;
132
133 //
134 // Implementation-specific Crypto functionality methods
135 //
136
137 /**
138 * Get an X509Certificate (chain) corresponding to the CryptoType argument. The supported
139 * types are as follows:
140 *
141 * TYPE.ISSUER_SERIAL - A certificate (chain) is located by the issuer name and serial number
142 * TYPE.THUMBPRINT_SHA1 - A certificate (chain) is located by the SHA1 of the (root) cert
143 * TYPE.SKI_BYTES - A certificate (chain) is located by the SKI bytes of the (root) cert
144 * TYPE.SUBJECT_DN - A certificate (chain) is located by the Subject DN of the (root) cert
145 * TYPE.ALIAS - A certificate (chain) is located by an alias. This alias is implementation
146 * specific, for example - it could be a java KeyStore alias.
147 */
148 X509Certificate[] getX509Certificates(CryptoType cryptoType) throws WSSecurityException;
149
150 /**
151 * Get the implementation-specific identifier corresponding to the cert parameter, e.g. the
152 * identifier could be a KeyStore alias.
153 * @param cert The X509Certificate for which to search for an identifier
154 * @return the identifier corresponding to the cert parameter
155 * @throws WSSecurityException
156 */
157 String getX509Identifier(X509Certificate cert) throws WSSecurityException;
158
159 /**
160 * Gets the private key corresponding to the certificate.
161 *
162 * @param certificate The X509Certificate corresponding to the private key
163 * @param callbackHandler The callbackHandler needed to get the password
164 * @return The private key
165 */
166 PrivateKey getPrivateKey(
167 X509Certificate certificate, CallbackHandler callbackHandler
168 ) throws WSSecurityException;
169
170 /**
171 * Gets the private key corresponding to the identifier.
172 *
173 * @param identifier The implementation-specific identifier corresponding to the key
174 * @param password The password needed to get the key
175 * @return The private key
176 */
177 PrivateKey getPrivateKey(
178 String identifier, String password
179 ) throws WSSecurityException;
180
181 /**
182 * Evaluate whether a given certificate chain should be trusted.
183 *
184 * @param certs Certificate chain to validate
185 * @return true if the certificate chain is valid, false otherwise
186 * @throws WSSecurityException
187 */
188 @Deprecated
189 boolean verifyTrust(X509Certificate[] certs) throws WSSecurityException;
190
191 /**
192 * Evaluate whether a given certificate chain should be trusted.
193 *
194 * @param certs Certificate chain to validate
195 * @param enableRevocation whether to enable CRL verification or not
196 * @return true if the certificate chain is valid, false otherwise
197 * @throws WSSecurityException
198 */
199 boolean verifyTrust(
200 X509Certificate[] certs, boolean enableRevocation
201 ) throws WSSecurityException;
202
203 /**
204 * Evaluate whether a given public key should be trusted.
205 *
206 * @param publicKey The PublicKey to be evaluated
207 * @return whether the PublicKey parameter is trusted or not
208 */
209 boolean verifyTrust(PublicKey publicKey) throws WSSecurityException;
210
211 }