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