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.wss4j.common.crypto;
20
21 import java.io.InputStream;
22 import java.security.PrivateKey;
23 import java.security.PublicKey;
24 import java.security.cert.CertificateFactory;
25 import java.security.cert.X509Certificate;
26 import java.util.Collection;
27 import java.util.regex.Pattern;
28
29 import javax.security.auth.callback.CallbackHandler;
30
31 import org.apache.wss4j.common.ext.WSSecurityException;
32
33 public interface Crypto {
34
35 //
36 // Accessor methods
37 //
38
39 /**
40 * Get the crypto provider associated with this implementation
41 * @return the crypto provider
42 */
43 String getCryptoProvider();
44
45 /**
46 * Set the crypto provider associated with this implementation
47 * @param provider the crypto provider name to set
48 */
49 void setCryptoProvider(String provider);
50
51 /**
52 * Get the crypto provider used for truststore operation associated with this implementation.
53 * @return a crypto provider name
54 */
55 String getTrustProvider();
56
57 /**
58 * Set the crypto provider used for truststore operations associated with this implementation
59 * @param provider the name of the provider
60 */
61 void setTrustProvider(String provider);
62
63 /**
64 * Retrieves the identifier name of the default certificate. This should be the certificate
65 * that is used for signature and encryption. This identifier corresponds to the certificate
66 * that should be used whenever KeyInfo is not present in a signed or an encrypted
67 * message. May return null. The identifier is implementation specific, e.g. it could be the
68 * KeyStore alias.
69 *
70 * @return name of the default X509 certificate.
71 */
72 String getDefaultX509Identifier() throws WSSecurityException;
73
74 /**
75 * Sets the identifier name of the default certificate. This should be the certificate
76 * that is used for signature and encryption. This identifier corresponds to the certificate
77 * that should be used whenever KeyInfo is not present in a signed or an encrypted
78 * message. The identifier is implementation specific, e.g. it could be the KeyStore alias.
79 *
80 * @param identifier name of the default X509 certificate.
81 */
82 void setDefaultX509Identifier(String identifier);
83
84 /**
85 * Sets the CertificateFactory instance on this Crypto instance
86 *
87 * @param certFactory the CertificateFactory the CertificateFactory instance to set
88 */
89 void setCertificateFactory(CertificateFactory certFactory);
90
91 /**
92 * Get the CertificateFactory instance on this Crypto instance
93 *
94 * @return Returns a <code>CertificateFactory</code> to construct
95 * X509 certificates
96 * @throws WSSecurityException
97 */
98 CertificateFactory getCertificateFactory() throws WSSecurityException;
99
100 //
101 // Base Crypto functionality methods
102 //
103
104 /**
105 * Load a X509Certificate from the input stream.
106 *
107 * @param in The <code>InputStream</code> containing the X509 data
108 * @return An X509 certificate
109 * @throws WSSecurityException
110 */
111 X509Certificate loadCertificate(InputStream in) throws WSSecurityException;
112
113 /**
114 * Reads the SubjectKeyIdentifier information from the certificate.
115 * <p/>
116 * If the the certificate does not contain a SKI extension then
117 * try to compute the SKI according to RFC3280 using the
118 * SHA-1 hash value of the public key. The second method described
119 * in RFC3280 is not support. Also only RSA public keys are supported.
120 * If we cannot compute the SKI throw a WSSecurityException.
121 *
122 * @param cert The certificate to read SKI
123 * @return The byte array containing the binary SKI data
124 */
125 byte[] getSKIBytesFromCert(X509Certificate cert) throws WSSecurityException;
126
127 /**
128 * Get a byte array given an array of X509 certificates.
129 * <p/>
130 *
131 * @param certs The certificates to convert
132 * @return The byte array for the certificates
133 * @throws WSSecurityException
134 */
135 byte[] getBytesFromCertificates(X509Certificate[] certs) throws WSSecurityException;
136
137 /**
138 * Construct an array of X509Certificate's from the byte array.
139 *
140 * @param data The <code>byte</code> array containing the X509 data
141 * @return An array of X509 certificates
142 * @throws WSSecurityException
143 */
144 X509Certificate[] getCertificatesFromBytes(byte[] data) throws WSSecurityException;
145
146 //
147 // Implementation-specific Crypto functionality methods
148 //
149
150 /**
151 * Get an X509Certificate (chain) corresponding to the CryptoType argument. The supported
152 * types are as follows:
153 *
154 * TYPE.ISSUER_SERIAL - A certificate (chain) is located by the issuer name and serial number
155 * TYPE.THUMBPRINT_SHA1 - A certificate (chain) is located by the SHA1 of the (root) cert
156 * TYPE.SKI_BYTES - A certificate (chain) is located by the SKI bytes of the (root) cert
157 * TYPE.SUBJECT_DN - A certificate (chain) is located by the Subject DN of the (root) cert
158 * TYPE.ALIAS - A certificate (chain) is located by an alias. This alias is implementation
159 * specific, for example - it could be a java KeyStore alias.
160 */
161 X509Certificate[] getX509Certificates(CryptoType cryptoType) throws WSSecurityException;
162
163 /**
164 * Get the implementation-specific identifier corresponding to the cert parameter, e.g. the
165 * identifier could be a KeyStore alias.
166 * @param cert The X509Certificate for which to search for an identifier
167 * @return the identifier corresponding to the cert parameter
168 * @throws WSSecurityException
169 */
170 String getX509Identifier(X509Certificate cert) throws WSSecurityException;
171
172 /**
173 * Gets the private key corresponding to the certificate.
174 *
175 * @param certificate The X509Certificate corresponding to the private key
176 * @param callbackHandler The callbackHandler needed to get the password
177 * @return The private key
178 */
179 PrivateKey getPrivateKey(
180 X509Certificate certificate, CallbackHandler callbackHandler
181 ) throws WSSecurityException;
182
183 /**
184 * Gets the private key corresponding to the given PublicKey.
185 *
186 * @param publicKey The PublicKey corresponding to the private key
187 * @param callbackHandler The callbackHandler needed to get the password
188 * @return The private key
189 */
190 PrivateKey getPrivateKey(
191 PublicKey publicKey,
192 CallbackHandler callbackHandler
193 ) throws WSSecurityException;
194
195 /**
196 * Gets the private key corresponding to the identifier.
197 *
198 * @param identifier The implementation-specific identifier corresponding to the key
199 * @param password The password needed to get the key
200 * @return The private key
201 */
202 PrivateKey getPrivateKey(
203 String identifier, String password
204 ) throws WSSecurityException;
205
206 /**
207 * Evaluate whether a given certificate chain should be trusted.
208 *
209 * @param certs Certificate chain to validate
210 * @param enableRevocation whether to enable CRL verification or not
211 * @param subjectCertConstraints A set of constraints on the Subject DN of the certificates
212 * @param issuerCertConstraints A set of constraints on the Issuer DN of the certificates
213 * @throws WSSecurityException if the certificate chain is invalid
214 */
215 void verifyTrust(
216 X509Certificate[] certs, boolean enableRevocation,
217 Collection<Pattern> subjectCertConstraints, Collection<Pattern> issuerCertConstraints
218 ) throws WSSecurityException;
219
220 /**
221 * Evaluate whether a given public key should be trusted.
222 *
223 * @param publicKey The PublicKey to be evaluated
224 * @throws WSSecurityException if the PublicKey is invalid
225 */
226 void verifyTrust(PublicKey publicKey) throws WSSecurityException;
227
228 }