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 legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2010 Sun Microsystems, Inc. 025 * Portions Copyright 2011-2014 ForgeRock AS 026 */ 027 028package org.forgerock.opendj.ldap.requests; 029 030import java.util.List; 031import java.util.Map; 032 033import org.forgerock.i18n.LocalizedIllegalArgumentException; 034import org.forgerock.opendj.ldap.DecodeException; 035import org.forgerock.opendj.ldap.DecodeOptions; 036import org.forgerock.opendj.ldap.LdapException; 037import org.forgerock.opendj.ldap.controls.Control; 038import org.forgerock.opendj.ldap.controls.ControlDecoder; 039 040/** 041 * The DIGEST-MD5 SASL bind request as defined in RFC 2831. This SASL mechanism 042 * allows a client to perform a challenge-response authentication method, 043 * similar to HTTP Digest Access Authentication. This mechanism can be used to 044 * negotiate integrity and/or privacy protection for the underlying connection. 045 * <p> 046 * Compared to CRAM-MD5, DIGEST-MD5 prevents chosen plain-text attacks, and 047 * permits the use of third party authentication servers, mutual authentication, 048 * and optimized re-authentication if a client has recently authenticated to a 049 * server. 050 * <p> 051 * The authentication and optional authorization identity is specified using an 052 * authorization ID, or {@code authzId}, as defined in RFC 4513 section 5.2.1.8. 053 * 054 * @see <a href="http://tools.ietf.org/html/rfc2831">RFC 2831 - Using Digest 055 * Authentication as a SASL Mechanism </a> 056 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 - 057 * SASL Authorization Identities (authzId) </a> 058 */ 059public interface DigestMD5SASLBindRequest extends SASLBindRequest { 060 061 /** 062 * Indicates that the client will accept connection encryption using the 063 * high strength triple-DES cipher. 064 */ 065 String CIPHER_3DES = "3des"; 066 067 /** 068 * Indicates that the client will accept connection encryption using the 069 * medium strength DES cipher. 070 */ 071 String CIPHER_DES = "des"; 072 073 /** 074 * Indicates that the client will accept connection encryption using the 075 * strongest supported cipher, as long as the cipher is considered to be 076 * high strength. 077 */ 078 String CIPHER_HIGH = "high"; 079 080 /** 081 * Indicates that the client will accept connection encryption using the 082 * strongest supported cipher, even if the strongest cipher is considered to 083 * be medium or low strength. 084 */ 085 String CIPHER_LOW = "low"; 086 087 /** 088 * Indicates that the client will accept connection encryption using the 089 * strongest supported cipher, as long as the cipher is considered to be 090 * high or medium strength. 091 */ 092 String CIPHER_MEDIUM = "medium"; 093 094 /** 095 * Indicates that the client will accept connection encryption using the 096 * high strength 128-bit RC4 cipher. 097 */ 098 String CIPHER_RC4_128 = "rc4"; 099 100 /** 101 * Indicates that the client will accept connection encryption using the low 102 * strength 40-bit RC4 cipher. 103 */ 104 String CIPHER_RC4_40 = "rc4-40"; 105 106 /** 107 * Indicates that the client will accept connection encryption using the 108 * medium strength 56-bit RC4 cipher. 109 */ 110 String CIPHER_RC4_56 = "rc4-56"; 111 112 /** 113 * Indicates that the client will accept authentication only. More 114 * specifically, the underlying connection will not be protected using 115 * integrity protection or encryption, unless previously established using 116 * SSL/TLS. This is the default if no QOP option is present in the bind 117 * request. 118 */ 119 String QOP_AUTH = "auth"; 120 121 /** 122 * Indicates that the client will accept authentication with connection 123 * integrity protection and encryption. 124 */ 125 String QOP_AUTH_CONF = "auth-conf"; 126 127 /** 128 * Indicates that the client will accept authentication with connection 129 * integrity protection. More specifically, the underlying connection will 130 * not be encrypted, unless previously established using SSL/TLS. 131 */ 132 String QOP_AUTH_INT = "auth-int"; 133 134 /** 135 * The name of the SASL mechanism based on DIGEST-MD5 authentication. 136 */ 137 String SASL_MECHANISM_NAME = "DIGEST-MD5"; 138 139 /** 140 * Adds the provided additional authentication parameter to the list of 141 * parameters to be passed to the underlying mechanism implementation. This 142 * method is provided in order to allow for future extensions. 143 * 144 * @param name 145 * The name of the additional authentication parameter. 146 * @param value 147 * The value of the additional authentication parameter. 148 * @return This bind request. 149 * @throws UnsupportedOperationException 150 * If this bind request does not permit additional 151 * authentication parameters to be added. 152 * @throws NullPointerException 153 * If {@code name} or {@code value} was {@code null}. 154 */ 155 DigestMD5SASLBindRequest addAdditionalAuthParam(String name, String value); 156 157 @Override 158 DigestMD5SASLBindRequest addControl(Control control); 159 160 /** 161 * Adds the provided quality of protection (QOP) values to the ordered list 162 * of QOP values that the client is willing to accept. The order of the list 163 * specifies the preference order, high to low. Authentication will fail if 164 * no QOP values are recognized or accepted by the server. 165 * <p> 166 * By default the client will accept {@link #QOP_AUTH AUTH}. 167 * 168 * @param qopValues 169 * The quality of protection values that the client is willing to 170 * accept. 171 * @return This bind request. 172 * @throws UnsupportedOperationException 173 * If this bind request does not permit QOP values to be added. 174 * @throws NullPointerException 175 * If {@code qopValues} was {@code null}. 176 * @see #QOP_AUTH 177 * @see #QOP_AUTH_INT 178 * @see #QOP_AUTH_CONF 179 */ 180 DigestMD5SASLBindRequest addQOP(String... qopValues); 181 182 @Override 183 BindClient createBindClient(String serverName) throws LdapException; 184 185 /** 186 * Returns a map containing the provided additional authentication 187 * parameters to be passed to the underlying mechanism implementation. This 188 * method is provided in order to allow for future extensions. 189 * 190 * @return A map containing the provided additional authentication 191 * parameters to be passed to the underlying mechanism 192 * implementation. 193 */ 194 Map<String, String> getAdditionalAuthParams(); 195 196 /** 197 * Returns the authentication ID of the user. The authentication ID usually 198 * has the form "dn:" immediately followed by the distinguished name of the 199 * user, or "u:" followed by a user ID string, but other forms are 200 * permitted. 201 * 202 * @return The authentication ID of the user. 203 */ 204 String getAuthenticationID(); 205 206 /** 207 * Returns the authentication mechanism identifier for this SASL bind 208 * request as defined by the LDAP protocol, which is always {@code 0xA3}. 209 * 210 * @return The authentication mechanism identifier. 211 */ 212 @Override 213 byte getAuthenticationType(); 214 215 /** 216 * Returns the optional authorization ID of the user which represents an 217 * alternate authorization identity which should be used for subsequent 218 * operations performed on the connection. The authorization ID usually has 219 * the form "dn:" immediately followed by the distinguished name of the 220 * user, or "u:" followed by a user ID string, but other forms are 221 * permitted. 222 * 223 * @return The authorization ID of the user, which may be {@code null}. 224 */ 225 String getAuthorizationID(); 226 227 /** 228 * Returns the cipher name or strength that the client is willing to use 229 * when connection encryption quality of protection, {@link #QOP_AUTH_CONF 230 * AUTH-CONF}, is requested. 231 * <p> 232 * By default the client will accept connection encryption using the 233 * strongest supported cipher, even if the strongest cipher is considered to 234 * be medium or low strength. This is equivalent to {@link #CIPHER_LOW}. 235 * 236 * @return The cipher that the client is willing to use if connection 237 * encryption QOP is negotiated. May be {@code null}, indicating 238 * that the default cipher should be used. 239 */ 240 String getCipher(); 241 242 @Override 243 <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) 244 throws DecodeException; 245 246 @Override 247 List<Control> getControls(); 248 249 /** 250 * Returns the maximum size of the receive buffer in bytes. The actual 251 * maximum number of bytes will be the minimum of this number and the peer's 252 * maximum send buffer size. The default size is 65536. 253 * 254 * @return The maximum size of the receive buffer in bytes. 255 */ 256 int getMaxReceiveBufferSize(); 257 258 /** 259 * Returns the maximum size of the send buffer in bytes. The actual maximum 260 * number of bytes will be the minimum of this number and the peer's maximum 261 * receive buffer size. The default size is 65536. 262 * 263 * @return The maximum size of the send buffer in bytes. 264 */ 265 int getMaxSendBufferSize(); 266 267 /** 268 * Returns the name of the Directory object that the client wishes to bind 269 * as, which is always the empty string for SASL authentication. 270 * 271 * @return The name of the Directory object that the client wishes to bind 272 * as. 273 */ 274 @Override 275 String getName(); 276 277 /** 278 * Returns the password of the user that the client wishes to bind as. 279 * <p> 280 * Unless otherwise indicated, implementations will store a reference to the 281 * returned password byte array, allowing applications to overwrite the 282 * password after it has been used. 283 * 284 * @return The password of the user that the client wishes to bind as. 285 */ 286 byte[] getPassword(); 287 288 /** 289 * Returns the ordered list of quality of protection (QOP) values that the 290 * client is willing to accept. The order of the list specifies the 291 * preference order, high to low. Authentication will fail if no QOP values 292 * are recognized or accepted by the server. 293 * <p> 294 * By default the client will accept {@link #QOP_AUTH AUTH}. 295 * 296 * @return The list of quality of protection values that the client is 297 * willing to accept. The returned list may be empty indicating that 298 * the default QOP will be accepted. 299 */ 300 List<String> getQOPs(); 301 302 /** 303 * Returns the optional realm containing the user's account. 304 * 305 * @return The name of the realm containing the user's account, which may be 306 * {@code null}. 307 */ 308 String getRealm(); 309 310 @Override 311 String getSASLMechanism(); 312 313 /** 314 * Returns {@code true} if the server must authenticate to the client. The 315 * default is {@code false}. 316 * 317 * @return {@code true} if the server must authenticate to the client. 318 */ 319 boolean isServerAuth(); 320 321 /** 322 * Sets the authentication ID of the user. The authentication ID usually has 323 * the form "dn:" immediately followed by the distinguished name of the 324 * user, or "u:" followed by a user ID string, but other forms are 325 * permitted. 326 * 327 * @param authenticationID 328 * The authentication ID of the user. 329 * @return This bind request. 330 * @throws LocalizedIllegalArgumentException 331 * If {@code authenticationID} was non-empty and did not contain 332 * a valid authorization ID type. 333 * @throws UnsupportedOperationException 334 * If this bind request does not permit the authentication ID to 335 * be set. 336 * @throws NullPointerException 337 * If {@code authenticationID} was {@code null}. 338 */ 339 DigestMD5SASLBindRequest setAuthenticationID(String authenticationID); 340 341 /** 342 * Sets the optional authorization ID of the user which represents an 343 * alternate authorization identity which should be used for subsequent 344 * operations performed on the connection. The authorization ID usually has 345 * the form "dn:" immediately followed by the distinguished name of the 346 * user, or "u:" followed by a user ID string, but other forms are 347 * permitted. 348 * 349 * @param authorizationID 350 * The authorization ID of the user, which may be {@code null}. 351 * @return This bind request. 352 * @throws LocalizedIllegalArgumentException 353 * If {@code authorizationID} was non-empty and did not contain 354 * a valid authorization ID type. 355 * @throws UnsupportedOperationException 356 * If this bind request does not permit the authorization ID to 357 * be set. 358 */ 359 DigestMD5SASLBindRequest setAuthorizationID(String authorizationID); 360 361 /** 362 * Sets the cipher name or strength that the client is willing to use when 363 * connection encryption quality of protection, {@link #QOP_AUTH_CONF 364 * AUTH-CONF}, is requested. 365 * <p> 366 * By default the client will accept connection encryption using the 367 * strongest supported cipher, even if the strongest cipher is considered to 368 * be medium or low strength. This is equivalent to {@link #CIPHER_LOW}. 369 * 370 * @param cipher 371 * The cipher that the client is willing to use if connection 372 * encryption QOP is negotiated. May be {@code null}, indicating 373 * that the default cipher should be used. 374 * @return This bind request. 375 * @throws UnsupportedOperationException 376 * If this bind request does not permit the cipher name or 377 * strength to be set. 378 * @see #QOP_AUTH_CONF 379 * @see #CIPHER_3DES 380 * @see #CIPHER_RC4_128 381 * @see #CIPHER_DES 382 * @see #CIPHER_RC4_56 383 * @see #CIPHER_RC4_40 384 * @see #CIPHER_HIGH 385 * @see #CIPHER_MEDIUM 386 * @see #CIPHER_LOW 387 */ 388 DigestMD5SASLBindRequest setCipher(String cipher); 389 390 /** 391 * Sets the maximum size of the receive buffer in bytes. The actual maximum 392 * number of bytes will be the minimum of this number and the peer's maximum 393 * send buffer size. The default size is 65536. 394 * 395 * @param size 396 * The maximum size of the receive buffer in bytes. 397 * @return This bind request. 398 * @throws UnsupportedOperationException 399 * If this bind request does not permit the buffer size to be 400 * set. 401 */ 402 DigestMD5SASLBindRequest setMaxReceiveBufferSize(int size); 403 404 /** 405 * Sets the maximum size of the send buffer in bytes. The actual maximum 406 * number of bytes will be the minimum of this number and the peer's maximum 407 * receive buffer size. The default size is 65536. 408 * 409 * @param size 410 * The maximum size of the send buffer in bytes. 411 * @return This bind request. 412 * @throws UnsupportedOperationException 413 * If this bind request does not permit the buffer size to be 414 * set. 415 */ 416 DigestMD5SASLBindRequest setMaxSendBufferSize(int size); 417 418 /** 419 * Sets the password of the user that the client wishes to bind as. 420 * <p> 421 * Unless otherwise indicated, implementations will store a reference to the 422 * provided password byte array, allowing applications to overwrite the 423 * password after it has been used. 424 * 425 * @param password 426 * The password of the user that the client wishes to bind as, 427 * which may be empty. 428 * @return This bind request. 429 * @throws UnsupportedOperationException 430 * If this bind request does not permit the password to be set. 431 * @throws NullPointerException 432 * If {@code password} was {@code null}. 433 */ 434 DigestMD5SASLBindRequest setPassword(byte[] password); 435 436 /** 437 * Sets the password of the user that the client wishes to bind as. The 438 * password will be converted to a UTF-8 octet string. 439 * 440 * @param password 441 * The password of the user that the client wishes to bind as. 442 * @return This bind request. 443 * @throws UnsupportedOperationException 444 * If this bind request does not permit the password to be set. 445 * @throws NullPointerException 446 * If {@code password} was {@code null}. 447 */ 448 DigestMD5SASLBindRequest setPassword(char[] password); 449 450 /** 451 * Sets the optional realm containing the user's account. 452 * 453 * @param realm 454 * The name of the realm containing the user's account, which may 455 * be {@code null}. 456 * @return This bind request. 457 * @throws UnsupportedOperationException 458 * If this bind request does not permit the realm to be set. 459 * @throws NullPointerException 460 * If {@code realm} was {@code null}. 461 */ 462 DigestMD5SASLBindRequest setRealm(String realm); 463 464 /** 465 * Specifies whether or not the server must authenticate to the client. The 466 * default is {@code false}. 467 * 468 * @param serverAuth 469 * {@code true} if the server must authenticate to the client or 470 * {@code false} otherwise. 471 * @return This bind request. 472 * @throws UnsupportedOperationException 473 * If this bind request does not permit server auth to be set. 474 */ 475 DigestMD5SASLBindRequest setServerAuth(boolean serverAuth); 476}