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