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 2012 ForgeRock AS. 026 */ 027 028package org.forgerock.opendj.ldap.requests; 029 030import java.util.List; 031 032import org.forgerock.opendj.ldap.ByteString; 033import org.forgerock.opendj.ldap.DecodeException; 034import org.forgerock.opendj.ldap.DecodeOptions; 035import org.forgerock.opendj.ldap.controls.Control; 036import org.forgerock.opendj.ldap.controls.ControlDecoder; 037import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder; 038import org.forgerock.opendj.ldap.responses.PasswordModifyExtendedResult; 039 040/** 041 * The password modify extended request as defined in RFC 3062. This operation 042 * allows directory clients to update user passwords. The user may or may not be 043 * associated with a directory entry. The user may or may not be represented as 044 * an LDAP DN. The user's password may or may not be stored in the directory. In 045 * addition, it includes support for requiring the user's current password as 046 * well as for generating a new password if none was provided. 047 * 048 * <pre> 049 * String userIdentity = ...; // For example, u:<uid> or dn:<DN> 050 * char[] oldPassword = ...; 051 * char[] newPassword = ...; 052 * Connection connection = ...; 053 * 054 * PasswordModifyExtendedRequest request = 055 * Requests.newPasswordModifyExtendedRequest() 056 * .setUserIdentity(userIdentity) 057 * .setOldPassword(oldPassword) 058 * .setNewPassword(newPassword); 059 * 060 * PasswordModifyExtendedResult result = connection.extendedRequest(request); 061 * if (result.isSuccess()) { 062 * // Changed password 063 * } else { 064 * // Use result to diagnose error. 065 * } 066 * </pre> 067 * 068 * @see PasswordModifyExtendedResult 069 * @see <a href="http://tools.ietf.org/html/rfc3062">RFC 3062 - LDAP Password 070 * Modify Extended Operation </a> 071 */ 072public interface PasswordModifyExtendedRequest extends 073 ExtendedRequest<PasswordModifyExtendedResult> { 074 075 /** 076 * A decoder which can be used to decode password modify extended operation 077 * requests. 078 */ 079 ExtendedRequestDecoder<PasswordModifyExtendedRequest, PasswordModifyExtendedResult> DECODER = 080 new PasswordModifyExtendedRequestImpl.RequestDecoder(); 081 082 /** 083 * The OID for the password modify extended operation request. 084 */ 085 String OID = "1.3.6.1.4.1.4203.1.11.1"; 086 087 @Override 088 PasswordModifyExtendedRequest addControl(Control control); 089 090 @Override 091 <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) 092 throws DecodeException; 093 094 @Override 095 List<Control> getControls(); 096 097 /** 098 * Returns the desired password for the user, or {@code null} if a new 099 * password should be generated. 100 * 101 * @return The desired password for the user, or {@code null} if a new 102 * password should be generated. 103 */ 104 byte[] getNewPassword(); 105 106 @Override 107 String getOID(); 108 109 /** 110 * Returns the current password for the user, if known. 111 * 112 * @return The current password for the user, or {@code null} if the 113 * password is not known. 114 */ 115 byte[] getOldPassword(); 116 117 @Override 118 ExtendedResultDecoder<PasswordModifyExtendedResult> getResultDecoder(); 119 120 /** 121 * Returns the identity of the user whose password is to be modified, or 122 * {@code null} if the request should be applied to the user currently 123 * associated with the session. The returned identity may or may not be a 124 * distinguished name. 125 * 126 * @return The identity of the user whose password is to be modified, or 127 * {@code null} if the request should be applied to the user 128 * currently associated with the session. 129 */ 130 ByteString getUserIdentity(); 131 132 /** 133 * Returns the identity of the user whose password is to be modified decoded 134 * as a UTF-8 string, or {@code null} if the request should be applied to 135 * the user currently associated with the session. The returned identity may 136 * or may not be a distinguished name. 137 * 138 * @return The identity of the user whose password is to be modified decoded 139 * as a UTF-8 string, or {@code null} if the request should be 140 * applied to the user currently associated with the session. 141 */ 142 String getUserIdentityAsString(); 143 144 @Override 145 ByteString getValue(); 146 147 @Override 148 boolean hasValue(); 149 150 /** 151 * Sets the desired password for the user. 152 * 153 * @param newPassword 154 * The desired password for the user, or {@code null} if a new 155 * password should be generated. 156 * @return This password modify request. 157 * @throws UnsupportedOperationException 158 * If this password modify extended request does not permit the 159 * new password to be set. 160 */ 161 PasswordModifyExtendedRequest setNewPassword(byte[] newPassword); 162 163 /** 164 * Sets the desired password for the user. The password will be converted to 165 * a UTF-8 octet string. 166 * 167 * @param newPassword 168 * The desired password for the user, or {@code null} if a new 169 * password should be generated. 170 * @return This password modify request. 171 * @throws UnsupportedOperationException 172 * If this password modify extended request does not permit the 173 * new password to be set. 174 */ 175 PasswordModifyExtendedRequest setNewPassword(char[] newPassword); 176 177 /** 178 * Sets the current password for the user. 179 * 180 * @param oldPassword 181 * The current password for the user, or {@code null} if the 182 * password is not known. 183 * @return This password modify request. 184 * @throws UnsupportedOperationException 185 * If this password modify extended request does not permit the 186 * old password to be set. 187 */ 188 PasswordModifyExtendedRequest setOldPassword(byte[] oldPassword); 189 190 /** 191 * Sets the current password for the user. The password will be converted to 192 * a UTF-8 octet string. 193 * 194 * @param oldPassword 195 * The current password for the user, or {@code null} if the 196 * password is not known. 197 * @return This password modify request. 198 * @throws UnsupportedOperationException 199 * If this password modify extended request does not permit the 200 * old password to be set. 201 */ 202 PasswordModifyExtendedRequest setOldPassword(char[] oldPassword); 203 204 /** 205 * Sets the identity of the user whose password is to be modified. The 206 * identity may or may not be a distinguished name. 207 * <p> 208 * If {@code userIdentity} is not an instance of {@code ByteString} then it 209 * will be converted using the {@link ByteString#valueOf(Object)} method. 210 * 211 * @param userIdentity 212 * The identity of the user whose password is to be modified, or 213 * {@code null} if the request should be applied to the user 214 * currently associated with the session. 215 * @return This password modify request. 216 * @throws UnsupportedOperationException 217 * If this password modify extended request does not permit the 218 * user identity to be set. 219 */ 220 PasswordModifyExtendedRequest setUserIdentity(Object userIdentity); 221 222}