Implementing extended operations by using IBM Security Verify Directory JNDI Toolkit

Edit online

An extended operation is a mechanism that allows more operations that are not defined in the LDAP protocol to be supported for services. These services are provided by LDAP V3 servers.

All additional operations that a server supports are to be sent by the client as an extended operation. An extended operation is called when a client sends an extended request and receives an extended response in response from the server. This communication between the client and server is broadly sequences as:
  1. A client sends an extended request to the server.
  2. If the server recognizes the request, it runs the operation.
  3. An extended response is sent back with the result, if any, for the operation.
When an extended operation is implemented by using JNDI, each extended operation has a request class and a response class. An extended request is made of two parts:
requestName
The requestName field contains a unique dotted decimal representation of the OID (Object Identifier) that identifies the request. The OID namespace is hierarchically divided, every authority that can define an OID is assigned a prefix that it uses to identify its OID.
requestValue
The requestValue field contains data that is needed to run the request. The format of the data is predefined for every extended operation. Some extended operations do not require any data to be associated with a request.
The extended request is encoded before it is sent to the server. IBM® Security Verify Directory requires the extended request to be ASN.1 BER encoded.

The javax.naming.ldap.ExtendedRequest interface describes an extended operation request. This interface contains methods getID() and getEncodedValue() that retrieve the two properties of an extended operation request, requestName and requestValue. A request class implements the javax.naming.ldap.ExtendedRequest interface and overrides the following methods of this interface public String getID() and public byte[] getEncodedValue(). This method retrieves ASN.1 BER encoded value from the LDAP extended operation request and constructs request sequence for the extended operation by using the com.ibm.asn1.BEREncoder class. This method then converts the encoded request sequence to byte array to be returned by the method.

The createExtendedResponse method creates the response object corresponding to a request. When a caller sends the extended operation request to the LDAP server, a response from the server is sent back. If the operation fails, the caller throws the NamingException exception. If the operation succeeds, the caller calls this method by using the data that it received in the response. The purpose of this method is to return an object of class that implements the ExtendedResponse interface that is appropriate for the extended operation request. 
public ExtendedResponse createExtendedResponse(
             String id,
             byte[] berValue,
             int offset, length) throws NamingException
The parameters that are passed to this method:
id
An object identifier of the response control.
berValue
An ASN.1 BER encoded value of the response control. This value is the raw BER bytes including the tag and length of the response value. It does not include the response OID.
offset
The starting position in the berValue of the bytes to use.
length
The number of bytes to use from berValue.
The structure of the extended response is similar to extended request. It can contain the OID and value both of which are optional, and a field that describes the result code of the operation. An extended response is made of three parts:
resultcode
The resultcode field contains result code of the operation. The result code can contain one of the defined LDAP error codes. For example, LDAP_SUCCESS and LDAP_OPERATIONS_ERROR.
responseName
The responseName field contains OID of the response. It might or might not be same as the request OID.
responseValue
The responseValue field contains the result of the operation, if any.
The response from the server is encoded in ASN.1 BER code and must be decoded by the client when received.

The javax.naming.ldap.ExtendedResponse interface describes an extended operation response. A response class implements the javax.naming.ldap.ExtendedResponse interface. The methods in this class can be used by the application to get low-level information about the extended operation response. This class parses the extended response and provides methods specific to that extended operations to return response values. It uses com.ibm.asn1.BERDecoder class to parse the response from the LDAP server. The BEREncoder and BERDecoder classes are part of current IBMLDAPJavaBer.jar shipped with IBM Security Verify Directory.

The Java™ classes for extended operations that are provided in IBM Security Verify Directory JNDI Toolkit are listed.
Table 1. Java classes for extended operations provided in IBM Security Verify Directory JNDI Toolkit
Extended operations Java classes Request OID or Response OID
Account status

AccountStatusRequest
AccountStatusResponse

1.3.18.0.2.12.58/
1.3.18.0.2.12.59
Attribute type

GetAttributesRequest
GetAttributesResponse

1.3.18.0.2.12.46 /
1.3.18.0.2.12.47
Begin transaction

TransactionStartRequest
TransactionStartResponse

1.3.18.0.2.12.5
Cascading replication operation

CascadingReplicationRequest
CascadingReplicationResponse

1.3.18.0.2.12.15
Clear log

ClearLogRequest
ClearLogResponse

1.3.18.0.2.12.20 /
1.3.18.0.2.12.21
Control replication

ControlReplicationRequest
ControlReplicationResponse

1.3.18.0.2.12.16
Control queue

ControlQueueRequest
ControlQueueResponse

1.3.18.0.2.12.17
DN normalization

NormalizeDNRequest
NormalizeDNResponse

1.3.18.0.2.12.30
Dynamic server trace

ControlTracingRequest
ControlTracingResponse

1.3.18.0.2.12.40
Dynamic update requests

ReadConfigurationRequest
ReadConfigurationResponse

1.3.18.0.2.12.28 /
1.3.18.0.2.12.29
End transaction

TransactionEndRequest
TransactionEndResponse

1.3.18.0.2.12.6
Effective password policy

EffectivePwdPolicyRequest
EffectivePwdPolicyResponse

1.3.18.0.2.12.75/
1.3.18.0.2.12.77
Event notification register request

RegisterEventRequest
RegisterEventResponse

1.3.18.0.2.12.1
Event notification unregister request

UnregisterEventRequest
UnregisterEventResponse

1.3.18.0.2.12.3
Get lines

ReadLogRequest
ReadLogResponse

1.3.18.0.2.12.22 /
1.3.18.0.2.12.23
Get number of lines

GetLogSizeRequest
GetLogSizeResponse

1.3.18.0.2.12.24 /
1.3.18.0.2.12.25
Group evaluation

EvaluateGroupsRequest
EvaluateGroupsResponse

1.3.18.0.2.12.50 /
1.3.18.0.2.12.52
Kill connection

UnbindRequest
UnbindResponse

1.3.18.0.2.12.35 /
1.3.18.0.2.12.36
LDAP trace facility

RemoteTraceExecutionRequest
RemoteTraceExecutionResponse

1.3.18.0.2.12.41
LogMgmtControl

LogManagementRequest
LogManagementresponse

1.3.18.0.2.12.70
Proxy back-end server resume role

ResumeRoleRequest
ResumeRoleResponse

1.3.18.0.2.12.65
Quiesce or unquiesce replication context

QuiesceRequest
QuiesceResponse

1.3.18.0.2.12.19
Replication error log

ControlReplErrorRequest
ControlReplErrorResponse

1.3.18.0.2.12.56
Replication topology

ReplicationTopologyRequest
ReplicationTopologyResponse

1.3.18.0.2.12.54 /
1.3.18.0.2.12.55
ServerBackupRestore

BackupRestoreRequest
BackupRestoreResponse

1.3.18.0.2.12.81
Start, stop server

StartStopServerRequest
StartStopServerResponse

1.3.18.0.2.12.26
Start TLS

StartTLSRequest
StartTLSResponse

1.3.6.1.4.1.1466.20037
Unique attributes

UniqueAttributeRequest
UniqueAttributeResponse

1.3.18.0.2.12.44 /
1.3.18.0.2.12.45
User type

UserTypeRequest
UserTypeResponse

1.3.18.0.2.12.37 /
1.3.18.0.2.12.38