001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2006-2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.types; 028 029 import org.opends.server.config.ConfigException; 030 031 import javax.crypto.Mac; 032 import javax.crypto.CipherOutputStream; 033 import javax.crypto.CipherInputStream; 034 import javax.net.ssl.SSLContext; 035 import java.security.MessageDigest; 036 import java.security.NoSuchAlgorithmException; 037 import java.security.GeneralSecurityException; 038 import java.io.InputStream; 039 import java.io.IOException; 040 import java.io.OutputStream; 041 import java.util.zip.DataFormatException; 042 import java.util.SortedSet; 043 044 /** 045 This interface defines the methods to call to access cryptographic 046 services including encryption and hashing; in particular, when the 047 ciphertext or HMAC is produced on one directory server instance and 048 is to be consumed on another. 049 */ 050 @org.opends.server.types.PublicAPI( 051 stability=org.opends.server.types.StabilityLevel.VOLATILE, 052 mayInstantiate=false, 053 mayExtend=false, 054 mayInvoke=true)public interface CryptoManager { 055 /** 056 * Retrieves the name of the preferred message digest algorithm. 057 * 058 * @return The name of the preferred message digest algorithm 059 */ 060 String getPreferredMessageDigestAlgorithm(); 061 062 /** 063 * Retrieves a <CODE>MessageDigest</CODE> object that may be used to 064 * generate digests using the preferred digest algorithm. 065 * 066 * @return A <CODE>MessageDigest</CODE> object that may be used to 067 * generate digests using the preferred digest algorithm. 068 * 069 * @throws java.security.NoSuchAlgorithmException If the requested 070 * algorithm is not supported or is unavailable. 071 */ 072 MessageDigest getPreferredMessageDigest() 073 throws NoSuchAlgorithmException; 074 075 /** 076 * Retrieves a <CODE>MessageDigest</CODE> object that may be used to 077 * generate digests using the specified algorithm. 078 * 079 * @param digestAlgorithm The algorithm to use to generate the 080 * message digest. 081 * 082 * @return A <CODE>MessageDigest</CODE> object that may be used to 083 * generate digests using the specified algorithm. 084 * 085 * @throws java.security.NoSuchAlgorithmException If the requested 086 * algorithm is not supported or is unavailable. 087 */ 088 MessageDigest getMessageDigest(String digestAlgorithm) 089 throws NoSuchAlgorithmException; 090 091 /** 092 * Retrieves a byte array containing a message digest based on the 093 * provided data, using the preferred digest algorithm. 094 * 095 * @param data The data to be digested. 096 * 097 * @return A byte array containing the generated message digest. 098 * 099 * @throws java.security.NoSuchAlgorithmException If the requested 100 * algorithm is not supported or is unavailable. 101 */ 102 byte[] digest(byte[] data) 103 throws NoSuchAlgorithmException; 104 105 /** 106 * Retrieves a byte array containing a message digest based on the 107 * provided data, using the requested digest algorithm. 108 * 109 * @param digestAlgorithm The algorithm to use to generate the 110 * message digest. 111 * @param data The data to be digested. 112 * 113 * @return A byte array containing the generated message digest. 114 * 115 * @throws java.security.NoSuchAlgorithmException If the requested 116 * algorithm is not supported or is unavailable. 117 */ 118 byte[] digest(String digestAlgorithm, byte[] data) 119 throws NoSuchAlgorithmException; 120 121 /** 122 * Retrieves a byte array containing a message digest based on the 123 * data read from the provided input stream, using the preferred 124 * digest algorithm. Data will be read until the end of the stream 125 * is reached. 126 * 127 * @param inputStream The input stream from which the data is to 128 * be read. 129 * 130 * @return A byte array containing the generated message digest. 131 * 132 * @throws java.io.IOException If a problem occurs while reading 133 * data from the provided stream. 134 * 135 * @throws java.security.NoSuchAlgorithmException If the requested 136 * algorithm is not supported or is unavailable. 137 */ 138 byte[] digest(InputStream inputStream) 139 throws IOException, NoSuchAlgorithmException; 140 141 /** 142 * Retrieves a byte array containing a message digest based on the 143 * data read from the provided input stream, using the requested 144 * digest algorithm. Data will be read until the end of the stream 145 * is reached. 146 * 147 * @param digestAlgorithm The algorithm to use to generate the 148 * message digest. 149 * @param inputStream The input stream from which the data is 150 * to be read. 151 * 152 * @return A byte array containing the generated message digest. 153 * 154 * @throws java.io.IOException If a problem occurs while reading 155 * data from the provided stream. 156 * 157 * @throws java.security.NoSuchAlgorithmException If the requested 158 * algorithm is not supported or is unavailable. 159 */ 160 byte[] digest(String digestAlgorithm, 161 InputStream inputStream) 162 throws IOException, NoSuchAlgorithmException; 163 164 /** 165 * For the current preferred MAC algorithm and key length, return 166 * the identifier of the corresponding key entry. Note: the result 167 * (key identifier) might change across invocations, due to either 168 * of the perferred parameters changing, or because the original 169 * key was marked compromised and a replacement key generated. 170 * 171 * @return A String representation of the identifier of a key entry 172 * corresponding to the preferred MAC algorithm and key length. 173 * 174 * @throws CryptoManagerException In case one or more of the key 175 * parameters is invalid, or there is a problem instantiating the 176 * key entry in case it does not already exist. 177 */ 178 String getMacEngineKeyEntryID() 179 throws CryptoManagerException; 180 181 /** 182 * For the specified MAC algorithm and key length, return 183 * the identifier of the corresponding key entry. Note: the result 184 * (key identifier) might change across invocations, due to either 185 * of the perferred parameters changing, or because the original 186 * key was marked compromised and a replacement key generated. 187 * 188 * @param macAlgorithm The algorithm to use for the MAC engine. 189 * 190 * @param keyLengthBits The key length in bits to use with the 191 * specified algorithm. 192 * 193 * @return A String representation of the identifier of a key entry 194 * corresponding to the specified MAC algorithm and key length. 195 * 196 * @throws CryptoManagerException In case one or more of the key 197 * parameters is invalid, or there is a problem instantiating the 198 * key entry in case it does not already exist. 199 */ 200 String getMacEngineKeyEntryID(String macAlgorithm, 201 int keyLengthBits) 202 throws CryptoManagerException; 203 204 /** 205 * For the specified key entry identifier, instantiate a MAC engine. 206 * 207 * @param keyEntryID The identifier of the key entry containing the 208 * desired MAC algorithm name and key length. 209 * 210 * @return The MAC engine instantiated with the parameters from the 211 * referenced key entry, or null if no such entry exists. 212 * 213 * @throws CryptoManagerException In case the key entry identifier 214 * is invalid or there is a problem instantiating the MAC engine 215 * from the parameters in the referenced key entry. 216 */ 217 Mac getMacEngine(String keyEntryID) 218 throws CryptoManagerException; 219 220 /** 221 * Encrypts the data in the provided byte array using the preferred 222 * cipher transformation. 223 * 224 * @param data The plain-text data to be encrypted. 225 * 226 * @return A byte array containing the encrypted representation of 227 * the provided data. 228 * 229 * @throws java.security.GeneralSecurityException If a problem 230 * occurs while encrypting the data. 231 * 232 * @throws CryptoManagerException If a problem occurs managing the 233 * encryption key or producing the cipher. 234 */ 235 byte[] encrypt(byte[] data) 236 throws GeneralSecurityException, CryptoManagerException; 237 238 /** 239 * Encrypts the data in the provided byte array using the requested 240 * cipher algorithm. 241 * 242 * @param cipherTransformation The algorithm/mode/padding to use 243 * for the cipher. 244 * 245 * @param keyLengthBits The length in bits of the encryption key 246 * this method is to use. Note the specified key length and 247 * transformation must be compatible. 248 * 249 * @param data The plain-text data to be encrypted. 250 * 251 * @return A byte array containing the encrypted representation of 252 * the provided data. 253 * 254 * @throws java.security.GeneralSecurityException If a problem 255 * occurs while encrypting the data. 256 * 257 * @throws CryptoManagerException If a problem occurs managing the 258 * encryption key or producing the cipher. 259 */ 260 byte[] encrypt(String cipherTransformation, 261 int keyLengthBits, 262 byte[] data) 263 throws GeneralSecurityException, CryptoManagerException; 264 265 /** 266 * Writes encrypted data to the provided output stream using the 267 * preferred cipher transformation. 268 * 269 * @param outputStream The output stream to be wrapped by the 270 * returned cipher output stream. 271 * 272 * @return The output stream wrapped with a CipherOutputStream. 273 * 274 * @throws CryptoManagerException If a problem occurs managing the 275 * encryption key or producing the cipher. 276 */ 277 CipherOutputStream getCipherOutputStream( 278 OutputStream outputStream) throws CryptoManagerException; 279 280 /** 281 * Writes encrypted data to the provided output stream using the 282 * requested cipher transformation. 283 * 284 * @param cipherTransformation The algorithm/mode/padding to use 285 * for the cipher. 286 * 287 * @param keyLengthBits The length in bits of the encryption key 288 * this method will generate. Note the specified key length 289 * must be compatible with the transformation. 290 * 291 * @param outputStream The output stream to be wrapped by the 292 * returned cipher output stream. 293 * 294 * @return The output stream wrapped with a CipherOutputStream. 295 * 296 * @throws CryptoManagerException If a problem occurs managing the 297 * encryption key or producing the cipher. 298 */ 299 CipherOutputStream getCipherOutputStream( 300 String cipherTransformation, int keyLengthBits, 301 OutputStream outputStream) 302 throws CryptoManagerException; 303 304 /** 305 * Decrypts the data in the provided byte array using cipher 306 * specified by the key identifier prologue to the data. 307 * cipher. 308 * 309 * @param data The cipher-text data to be decrypted. 310 * 311 * @return A byte array containing the clear-text representation of 312 * the provided data. 313 * 314 * @throws java.security.GeneralSecurityException If a problem 315 * occurs while encrypting the data. 316 * 317 * @throws CryptoManagerException If a problem occurs reading the 318 * key identifier or initialization vector from the data 319 * prologue, or using these values to initialize a Cipher. 320 */ 321 byte[] decrypt(byte[] data) 322 throws GeneralSecurityException, 323 CryptoManagerException; 324 325 /** 326 * Returns a CipherInputStream instantiated with a cipher 327 * corresponding to the key identifier prologue to the data. 328 * 329 * @param inputStream The input stream be wrapped with the 330 * CipherInputStream. 331 * 332 * @return The CiperInputStream instantiated as specified. 333 * 334 * @throws CryptoManagerException If there is a problem reading the 335 * key ID or initialization vector from the input stream, 336 * or using these values to inititalize a Cipher. 337 */ 338 CipherInputStream getCipherInputStream( 339 InputStream inputStream) throws CryptoManagerException; 340 341 /** 342 * Attempts to compress the data in the provided source array into 343 * the given destination array. If the compressed data will fit 344 * into the destination array, then this method will return the 345 * number of bytes of compressed data in the array. Otherwise, it 346 * will return -1 to indicate that the compression was not 347 * successful. Note that if -1 is returned, then the data in the 348 * destination array should be considered invalid. 349 * 350 * @param src The array containing the raw data to compress. 351 * @param dst The array into which the compressed data should be 352 * written. 353 * 354 * @return The number of bytes of compressed data, or -1 if it was 355 * not possible to actually compress the data. 356 */ 357 int compress(byte[] src, byte[] dst); 358 359 /** 360 * Attempts to uncompress the data in the provided source array into 361 * the given destination array. If the uncompressed data will fit 362 * into the given destination array, then this method will return 363 * the number of bytes of uncompressed data written into the 364 * destination buffer. Otherwise, it will return a negative value 365 * to indicate that the destination buffer was not large enough. 366 * The absolute value of that negative return value will indicate 367 * the buffer size required to fully decompress the data. Note that 368 * if a negative value is returned, then the data in the destination 369 * array should be considered invalid. 370 * 371 * @param src The array containing the compressed data. 372 * @param dst The array into which the uncompressed data should be 373 * written. 374 * 375 * @return A positive value containing the number of bytes of 376 * uncompressed data written into the destination buffer, 377 * or a negative value whose absolute value is the size of 378 * the destination buffer required to fully decompress the 379 * provided data. 380 * 381 * @throws java.util.zip.DataFormatException If a problem occurs 382 * while attempting to uncompress the data. 383 */ 384 int uncompress(byte[] src, byte[] dst) 385 throws DataFormatException; 386 387 /** 388 * Create an SSL context that may be used for communication to 389 * another ADS component. 390 * 391 * @param sslCertNickname The name of the local certificate to use, 392 * or null if none is specified. 393 * @return A new SSL Context. 394 * @throws org.opends.server.config.ConfigException If the context 395 * could not be created. 396 */ 397 SSLContext getSslContext(String sslCertNickname) 398 throws ConfigException; 399 400 /** 401 * Get the name of the local certificate to use for SSL. 402 * @return The name of the local certificate to use for SSL. 403 */ 404 String getSslCertNickname(); 405 406 /** 407 * Determine whether SSL encryption is enabled. 408 * @return true if SSL encryption is enabled. 409 */ 410 boolean isSslEncryption(); 411 412 /** 413 * Get the set of enabled SSL protocols. 414 * @return The set of enabled SSL protocols. 415 */ 416 SortedSet<String> getSslProtocols(); 417 418 /** 419 * Get the set of enabled SSL cipher suites. 420 * @return The set of enabled SSL cipher suites. 421 */ 422 SortedSet<String> getSslCipherSuites(); 423 }