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 javax.security.auth.Subject; 034 035import org.forgerock.i18n.LocalizedIllegalArgumentException; 036import org.forgerock.opendj.ldap.DecodeException; 037import org.forgerock.opendj.ldap.DecodeOptions; 038import org.forgerock.opendj.ldap.LdapException; 039import org.forgerock.opendj.ldap.controls.Control; 040import org.forgerock.opendj.ldap.controls.ControlDecoder; 041 042/** 043 * The GSSAPI SASL bind request as defined in RFC 2831. This SASL mechanism 044 * allows a client to use the Generic Security Service Application Program 045 * Interface (GSS-API) Kerberos V5 to authenticate to the server. This mechanism 046 * can be used to negotiate integrity and/or privacy protection for the 047 * underlying connection. 048 * <p> 049 * The optional authorization identity is specified using an authorization ID, 050 * or {@code authzId}, as defined in RFC 4513 section 5.2.1.8. 051 * 052 * @see <a href="http://tools.ietf.org/html/rfc4752">RFC 4752 - The Kerberos V5 053 * ("GSSAPI") Simple Authentication and Security Layer (SASL) Mechanism 054 * </a> 055 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 - 056 * SASL Authorization Identities (authzId) </a> 057 */ 058public interface GSSAPISASLBindRequest extends SASLBindRequest { 059 060 /** 061 * Indicates that the client will accept authentication only. More 062 * specifically, the underlying connection will not be protected using 063 * integrity protection or encryption, unless previously established using 064 * SSL/TLS. This is the default if no QOP option is present in the bind 065 * request. 066 */ 067 String QOP_AUTH = "auth"; 068 069 /** 070 * Indicates that the client will accept authentication with connection 071 * integrity protection and encryption. 072 */ 073 String QOP_AUTH_CONF = "auth-conf"; 074 075 /** 076 * Indicates that the client will accept authentication with connection 077 * integrity protection. More specifically, the underlying connection will 078 * not be encrypted, unless previously established using SSL/TLS. 079 */ 080 String QOP_AUTH_INT = "auth-int"; 081 082 /** 083 * The name of the SASL mechanism based on GSS-API authentication. 084 */ 085 String SASL_MECHANISM_NAME = "GSSAPI"; 086 087 /** 088 * Adds the provided additional authentication parameter to the list of 089 * parameters to be passed to the underlying mechanism implementation. This 090 * method is provided in order to allow for future extensions. 091 * 092 * @param name 093 * The name of the additional authentication parameter. 094 * @param value 095 * The value of the additional authentication parameter. 096 * @return This bind request. 097 * @throws UnsupportedOperationException 098 * If this bind request does not permit additional 099 * authentication parameters to be added. 100 * @throws NullPointerException 101 * If {@code name} or {@code value} was {@code null}. 102 */ 103 GSSAPISASLBindRequest addAdditionalAuthParam(String name, String value); 104 105 @Override 106 GSSAPISASLBindRequest addControl(Control control); 107 108 /** 109 * Adds the provided quality of protection (QOP) values to the ordered list 110 * of QOP values that the client is willing to accept. The order of the list 111 * specifies the preference order, high to low. Authentication will fail if 112 * no QOP values are recognized or accepted by the server. 113 * <p> 114 * By default the client will accept {@link #QOP_AUTH AUTH}. 115 * 116 * @param qopValues 117 * The quality of protection values that the client is willing to 118 * accept. 119 * @return This bind request. 120 * @throws UnsupportedOperationException 121 * If this bind request does not permit QOP values to be added. 122 * @throws NullPointerException 123 * If {@code qopValues} was {@code null}. 124 * @see #QOP_AUTH 125 * @see #QOP_AUTH_INT 126 * @see #QOP_AUTH_CONF 127 */ 128 GSSAPISASLBindRequest addQOP(String... qopValues); 129 130 @Override 131 BindClient createBindClient(String serverName) throws LdapException; 132 133 /** 134 * Returns a map containing the provided additional authentication 135 * parameters to be passed to the underlying mechanism implementation. This 136 * method is provided in order to allow for future extensions. 137 * 138 * @return A map containing the provided additional authentication 139 * parameters to be passed to the underlying mechanism 140 * implementation. 141 */ 142 Map<String, String> getAdditionalAuthParams(); 143 144 /** 145 * Returns the authentication ID of the user, which should be the user's 146 * Kerberos principal. The authentication ID usually has the form "dn:" 147 * immediately followed by the distinguished name of the user, or "u:" 148 * followed by a user ID string, but other forms are permitted. 149 * <p> 150 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 151 * 152 * @return The authentication ID of the user. 153 */ 154 String getAuthenticationID(); 155 156 /** 157 * Returns the authentication mechanism identifier for this SASL bind 158 * request as defined by the LDAP protocol, which is always {@code 0xA3}. 159 * 160 * @return The authentication mechanism identifier. 161 */ 162 @Override 163 byte getAuthenticationType(); 164 165 /** 166 * Returns the optional authorization ID of the user which represents an 167 * alternate authorization identity which should be used for subsequent 168 * operations performed on the connection. The authorization ID usually has 169 * the form "dn:" immediately followed by the distinguished name of the 170 * user, or "u:" followed by a user ID string, but other forms are 171 * permitted. 172 * 173 * @return The authorization ID of the user, which may be {@code null}. 174 */ 175 String getAuthorizationID(); 176 177 @Override 178 <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) 179 throws DecodeException; 180 181 @Override 182 List<Control> getControls(); 183 184 /** 185 * Returns the optional address of the Kerberos KDC (Key Distribution 186 * Center). 187 * <p> 188 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 189 * 190 * @return The address of the Kerberos KDC (Key Distribution Center), which 191 * may be {@code null}. 192 */ 193 String getKDCAddress(); 194 195 /** 196 * Returns the maximum size of the receive buffer in bytes. The actual 197 * maximum number of bytes will be the minimum of this number and the peer's 198 * maximum send buffer size. The default size is 65536. 199 * 200 * @return The maximum size of the receive buffer in bytes. 201 */ 202 int getMaxReceiveBufferSize(); 203 204 /** 205 * Returns the maximum size of the send buffer in bytes. The actual maximum 206 * number of bytes will be the minimum of this number and the peer's maximum 207 * receive buffer size. The default size is 65536. 208 * 209 * @return The maximum size of the send buffer in bytes. 210 */ 211 int getMaxSendBufferSize(); 212 213 /** 214 * Returns the name of the Directory object that the client wishes to bind 215 * as, which is always the empty string for SASL authentication. 216 * 217 * @return The name of the Directory object that the client wishes to bind 218 * as. 219 */ 220 @Override 221 String getName(); 222 223 /** 224 * Returns the password of the user that the client wishes to bind as. 225 * <p> 226 * Unless otherwise indicated, implementations will store a reference to the 227 * returned password byte array, allowing applications to overwrite the 228 * password after it has been used. 229 * <p> 230 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 231 * 232 * @return The password of the user that the client wishes to bind as. 233 */ 234 byte[] getPassword(); 235 236 /** 237 * Returns the ordered list of quality of protection (QOP) values that the 238 * client is willing to accept. The order of the list specifies the 239 * preference order, high to low. Authentication will fail if no QOP values 240 * are recognized or accepted by the server. 241 * <p> 242 * By default the client will accept {@link #QOP_AUTH AUTH}. 243 * 244 * @return The list of quality of protection values that the client is 245 * willing to accept. The returned list may be empty indicating that 246 * the default QOP will be accepted. 247 */ 248 List<String> getQOPs(); 249 250 /** 251 * Returns the optional realm containing the user's account. 252 * <p> 253 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 254 * 255 * @return The name of the realm containing the user's account, which may be 256 * {@code null}. 257 */ 258 String getRealm(); 259 260 @Override 261 String getSASLMechanism(); 262 263 /** 264 * Returns the Kerberos subject of the user to be authenticated. 265 * <p> 266 * <b>NOTE</b>: if a {@code Subject} is specified then the authentication 267 * ID, KDC address, password, and realm, will be ignored. 268 * 269 * @return The Kerberos subject of the user to be authenticated. 270 */ 271 Subject getSubject(); 272 273 /** 274 * Returns {@code true} if the server must authenticate to the client. The 275 * default is {@code false}. 276 * 277 * @return {@code true} if the server must authenticate to the client. 278 */ 279 boolean isServerAuth(); 280 281 /** 282 * Sets the authentication ID of the user, which should be the user's 283 * Kerberos principal. The authentication ID usually has the form "dn:" 284 * immediately followed by the distinguished name of the user, or "u:" 285 * followed by a user ID string, but other forms are permitted. 286 * <p> 287 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 288 * 289 * @param authenticationID 290 * The authentication ID of the user. 291 * @return This bind request. 292 * @throws LocalizedIllegalArgumentException 293 * If {@code authenticationID} was non-empty and did not contain 294 * a valid authorization ID type. 295 * @throws NullPointerException 296 * If {@code authenticationID} was {@code null}. 297 */ 298 GSSAPISASLBindRequest setAuthenticationID(String authenticationID); 299 300 /** 301 * Sets the optional authorization ID of the user which represents an 302 * alternate authorization identity which should be used for subsequent 303 * operations performed on the connection. The authorization ID usually has 304 * the form "dn:" immediately followed by the distinguished name of the 305 * user, or "u:" followed by a user ID string, but other forms are 306 * permitted. 307 * 308 * @param authorizationID 309 * The authorization ID of the user, which may be {@code null}. 310 * @return This bind request. 311 * @throws LocalizedIllegalArgumentException 312 * If {@code authorizationID} was non-empty and did not contain 313 * a valid authorization ID type. 314 */ 315 GSSAPISASLBindRequest setAuthorizationID(String authorizationID); 316 317 /** 318 * Sets the optional address of the Kerberos KDC (Key Distribution Center). 319 * <p> 320 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 321 * 322 * @param address 323 * The address of the Kerberos KDC (Key Distribution Center), 324 * which may be {@code null}. 325 * @return This bind request. 326 * @throws UnsupportedOperationException 327 * If this bind request does not permit the KDC address to be 328 * set. 329 * @throws NullPointerException 330 * If {@code address} was {@code null}. 331 */ 332 GSSAPISASLBindRequest setKDCAddress(String address); 333 334 /** 335 * Sets the maximum size of the receive buffer in bytes. The actual maximum 336 * number of bytes will be the minimum of this number and the peer's maximum 337 * send buffer size. The default size is 65536. 338 * 339 * @param size 340 * The maximum size of the receive buffer in bytes. 341 * @return This bind request. 342 * @throws UnsupportedOperationException 343 * If this bind request does not permit the buffer size to be 344 * set. 345 */ 346 GSSAPISASLBindRequest setMaxReceiveBufferSize(int size); 347 348 /** 349 * Sets the maximum size of the send buffer in bytes. The actual maximum 350 * number of bytes will be the minimum of this number and the peer's maximum 351 * receive buffer size. The default size is 65536. 352 * 353 * @param size 354 * The maximum size of the send buffer in bytes. 355 * @return This bind request. 356 * @throws UnsupportedOperationException 357 * If this bind request does not permit the buffer size to be 358 * set. 359 */ 360 GSSAPISASLBindRequest setMaxSendBufferSize(int size); 361 362 /** 363 * Sets the password of the user that the client wishes to bind as. 364 * <p> 365 * Unless otherwise indicated, implementations will store a reference to the 366 * provided password byte array, allowing applications to overwrite the 367 * password after it has been used. 368 * <p> 369 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 370 * 371 * @param password 372 * The password of the user that the client wishes to bind as, 373 * which may be empty. 374 * @return This bind request. 375 * @throws UnsupportedOperationException 376 * If this bind request does not permit the password to be set. 377 * @throws NullPointerException 378 * If {@code password} was {@code null}. 379 */ 380 GSSAPISASLBindRequest setPassword(byte[] password); 381 382 /** 383 * Sets the password of the user that the client wishes to bind as. The 384 * password will be converted to a UTF-8 octet string. 385 * <p> 386 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 387 * 388 * @param password 389 * The password of the user that the client wishes to bind as. 390 * @return This bind request. 391 * @throws UnsupportedOperationException 392 * If this bind request does not permit the password to be set. 393 * @throws NullPointerException 394 * If {@code password} was {@code null}. 395 */ 396 GSSAPISASLBindRequest setPassword(char[] password); 397 398 /** 399 * Sets the optional realm containing the user's account. 400 * <p> 401 * <b>NOTE</b>: this will not be used if a {@code Subject} is specified. 402 * 403 * @param realm 404 * The name of the realm containing the user's account, which may 405 * be {@code null}. 406 * @return This bind request. 407 * @throws UnsupportedOperationException 408 * If this bind request does not permit the realm to be set. 409 * @throws NullPointerException 410 * If {@code realm} was {@code null}. 411 */ 412 GSSAPISASLBindRequest setRealm(String realm); 413 414 /** 415 * Specifies whether or not the server must authenticate to the client. The 416 * default is {@code false}. 417 * 418 * @param serverAuth 419 * {@code true} if the server must authenticate to the client or 420 * {@code false} otherwise. 421 * @return This bind request. 422 * @throws UnsupportedOperationException 423 * If this bind request does not permit server auth to be set. 424 */ 425 GSSAPISASLBindRequest setServerAuth(boolean serverAuth); 426 427 /** 428 * Sets the Kerberos subject of the user to be authenticated. 429 * <p> 430 * <b>NOTE</b>: if a {@code Subject} is specified then the authentication 431 * ID, KDC address, password, and realm, will be ignored. 432 * 433 * @param subject 434 * The Kerberos subject of the user to be authenticated. 435 * @return This bind request. 436 * @throws UnsupportedOperationException 437 * If this bind request does not permit the Kerberos subject to 438 * be set. 439 * @throws NullPointerException 440 * If {@code subject} was {@code null}. 441 */ 442 GSSAPISASLBindRequest setSubject(Subject subject); 443}