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