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 }