Table 5.22 The parameters of the RemoveEntry operation
| RemoveEntry Arguments | ASN.1 Parameter Encoding | Described in |
| The (distinguished?) name of the entry to be deleted | Distinguished Name | 5.14 |
| Common Arguments | See § 5.4 | 5.13.1 |
The operation is usually simple to implement compared to the AddEntry operation (but see § 5.14.1), but may be complicated by implementation specific enhancements such as indices. The main checks that need to be performed are those of security. Is the user authorised, and does the user have the necessary permission to remove the entry (Chapter 8)? Note that the user must provide the distinguished name of the entry to be deleted for '88 edition DSAs, and at the time of writing, the issue is unresolved for '93 edition DSAs.
Note. If the HOB is NHOB, it is only terminated if this is the last subordinate entry in the subordinate DSA.
This termination may be performed before the entry is deleted, whilst it is being deleted, or after it has been deleted. It may be deleted manually or automatically by using the Standardised DOP protocol. Failure to delete the RHOB will leave a subordinate reference in the superior DSA, pointing to a non-existent entry in the subordinate DSA.
Table 5.23 The parameters of the ModifyEntry operation
| ModifyEntry Arguments | ASN.1 Parameter Encoding | Described in |
| The name of the entry to be modified | (Distinguished) Name | 5.15 |
| The sequence of changes to be made to the entry, each change
comprising either:
adding an attribute removing an attribute adding one or more attribute values, or removing one or more attribute values |
SEQUENCE OF CHOICE { Attribute AttributeType Attribute Attribute } |
5.15 |
| Common Arguments | see § 5.4 | 5.13.1 |
One difference between the '88 and '93 Standards is the name presented by the user. '88 DSAs expect the distinguished name of the entry to be modified. '93 DSAs are happy to accept alias names and to perform alias dereferencing before modifying the entry.
Each of the changes is applied in turn. If any single change fails, then the entire operation fails. A partial modification will not be applied. The whole operation is thus atomic. (Atomic operations have the characteristic that intermediate internal states are not visible to other operations. Only the initial and final states are externally visible.) An attribute must not exist in the entry at the time it is added. An attribute must exist in the entry at the time it is removed, or when values are added or removed from it. Violation of any of these rules will cause the operation to fail.
The modified attributes of the entry, after the application of all of the changes, must conform to the subschema for the entry (or system schema in the case of subentries). It is recognised that the entry and/or its attributes may not conform to the subschema part way through the application of the changes, but since these transient states are not visible outside of the operation, this is acceptable. For example, suppose I wanted to re-configure an X.400 Message Transfer Agent, and this object had an entry in the Directory. In order to add the new presentation address into the Directory entry, I might specify the sequence of changes: Remove attribute presentation address, Add attribute presentation address with value '....'. Subschemas usually mandate that all application entities must have a presentation address attribute. The X.400 MTA entry has a presentation address attribute before and after the application of the modification operation, and so the operation will succeed. The fact that a transient state existed, during which time the entry did not have a presentation address attribute, is disregarded for schema checking purposes.
It is also recognised that, in exceptional circumstances, an entry may not conform to the subschema prior to the application of the ModifyEntry operation. This is the case when the subschema has been updated, but the entries in the subschema administrative area have not yet been updated to be consistent with the new subschema. ModifyEntry is still allowed in this situation, provided that the operation does not make the entry less consistent, and that the particular attributes that are updated are conformant to the new subschema.
The ModifyEntry operation may be used to modify Directory operational attributes held in the entry, providing that these have been defined as user modifiable (§ 3.4).
Care needs to be taken in '93 DSAs that support collective attributes. Although collective attributes appear to be in an entry, they are not actually held there, and so cannot be directly modified. A collective attribute may only be modified by applying the ModifyEntry operation to the subentry that holds it. A collective attribute can only be removed from being visible in a normal entry, by either modifying the DIT content rule that makes it visible in the entry, or by adding its attribute type to the collective exclusions operational attribute of the entry, or by modifying the subentry subtree specification that includes the entry in its scope, or by deleting the collective attribute from the subentry. (Note. The collective exclusions operational attribute, is used on a per entry basis, to exclude a collective attribute from being visible in that entry. All the other ways of manipulating collective attributes, do so by operating on groups of entries, which share either the same object class or subtree of the DIT.) All of these changes would normally require the administrator to perform them. Normal users are effectively banned from modifying collective attributes.
Finally, the object class attribute of an entry can be modified, providing that only the auxiliary object classes are changed. Remember that the attributes that are declared mandatory and optional in the auxiliary object class definitions, may need to be modified at the same time. The entry will have to conform to the subschema after the changes have been applied.
Fig. 5.7 An example of a ModifyEntry request.
The parameters of the ModifyDN operation are given in Table 5.24. The distinguished name of the entry to be renamed must always be quoted.
If the operation is to be used to modify the RDN of an entry, then the parameter distinguished name of the new superior will be absent. If the operation is intended to move an entry (and its subordinates) to a new superior, but to keep its existing relative distinguished name, then the parameter new RDN for the entry will be the same as the current RDN of the entry. If the operation is intended to move an entry and rename its RDN, then the new RDN will be different from the current one.
The new RDN can be constructed from attribute values that already exist in the entry, or new values can be input. The only restriction is that the subschema (name form) must be obeyed by the new name.
The attribute values that comprise the old RDN will normally be left in the entry, unless the delete old RDN flag is set to True. In this case the values will be deleted.
Table 5.24 The parameters of the ModifyDN operation
| ModifyDN Arguments | ASN.1 Parameter Encoding | Described in |
| The distinguished name of the entry to be renamed | DistinguishedName | 5.16 |
| The new relative distinguished name for the entry | RelativeDistinguishedName | 5.16 |
| Flag for deleting the old RDN from the entry | BOOLEAN DEFAULT FALSE | 5.16 |
| *The distinguished name of the new superior of the entry | DistinguishedName OPTIONAL | 5.16 |
| Common Arguments | see § 5.4 | 5.13.1 |
When moving an entry, the new superior entry must already exist as a master entry in the DSA. The new superior obviously cannot be an alias or a subentry, as these are not allowed to have subordinates. Neither can it be the entry itself or any of its subordinates! The move will only be performed if the subschema (DIT structure rules) controlling the new superior and its subordinates, allows the moved entry to be placed beneath it. Without an appropriate subschema, the entry cannot be moved to its new home. However, if the moved entry has subordinates, these do not need to be checked for subschema conformance at the time of the move. This can be done later by the system administrator. It was judged by some implementors in the Standard's group to be too processor intensive to check the subschema of all of the subordinates at the time of the move, and would cause too long a delay before the operation could be completed. (This obviously depends upon the size of the subtree.)
A discussion of the access rights needed for this operation is given in Chapter 8.
Fig. 5.8 An example of a ModifyDN request.
When entries are shadowed, their controlling subentries are copied along with them. Thus when subentries are added, removed, modified or renamed, the appropriate shadowing DSAs will need to be updated (§ 6.3.2).
It can be seen that a single modify operation to a subentry may cause many other operations to be initiated as a result. Administrators need to be aware that subentry modifications can have this explosive effect.
Eight different types of error are defined by the Standard. These have been given the ROSE Remote Error identifiers 1 to 8, and they are described in order below.
Note. A similar numbering scheme for the operations, uses the numbers 1 to 9 to identify in the protocol the Remote Operations Read through to ModifyDN.
Each type of error has an associated set of parameters, which are listed in Tables 5.25 - 5.29. Where it is possible, the individual parameters are encoded as integers, again to minimise the data transferred in the protocol.
In the definition of each operation, there is a list of which errors can be reported. Most operations are able to report most of the errors. There are some obvious exceptions. The interrogation operations cannot report an Update Error! The Abandon operation can only report an Abandon Failed error. I do not propose to give a complete list here. Interested readers should consult the Standard.
The main thing that is missing from the Standard, is a description of which error should be generated under which circumstances. This proved to be a problem to implementors, who found that several errors might apply to one situation, and that none of the defined errors appeared to apply in another. These problems have been solved by the publication of the EWOS Technical Guide ETG 017 [3.9]. This document describes in some detail, which error should be reported in which situation. It also gives guidance to chaining DSAs, on which error to relay back when a choice is available. (It was also necessary to raise a defect report on the Standard, which resulted in the widening of the definition of when the Update Error (Entry Already Exists) could be reported.)
It is interesting to note that when the '93 edition of the Standard was produced, with all its enhanced facilities, only one new error diagnostic had to be created (to support paged results), and several of the existing ones had their semantics widened.
Table 5.25 The parameters of the Attribute Error
| Attribute Error Parameter | ASN.1 Parameter Encoding |
| The name of the entry being operated on when the error occurred | RDNSequence |
| The problem that occurred, either
No Such Attribute Or Value Invalid Attribute Syntax Undefined Attribute Type Inappropriate Matching Rule Constraint Violation or Attribute Or Value Already Exists. |
INTEGER
1, 2, 3, 4, 5, 6. |
| The attribute that caused the problem | AttributeType |
| The attribute value that caused the problem | AttributeValue OPTIONAL |
If more than one problem was detected, the DSA software is allowed to return a series of problems. Usually this will not be the case, since many implementations will stop processing a request when the first error occurs. Each diagnosed problem is accompanied by the attribute type that caused the problem. If a particular problem requires it e.g. an attempt is made to add an already existing attribute value, then the problem code is also accompanied by the offending attribute value.
Table 5.26 The parameters of the Name Error
| Name Error Parameter | ASN.1 Parameter Encoding |
| The problem that was encountered, either
No Such Object Alias Problem Invalid Attribute Syntax or Alias Dereferencing Problem. |
INTEGER
1, 2, 3, 4. |
| The part of the name that was correct and that matched entries in the DIT | RDNSequence |
When replication is supported in the part of the Directory being contacted, then some of the problems e.g. busy, may be soft errors that may be by-passed by contacting another DSA. Other problems e.g. out of scope, are hard errors which will cause a failure whichever DSA is contacted (§ 9.12).
Table 5.27 The parameters of the Service Error
| Service Error Problem (Code) | Meaning |
| Busy (1) | A DSA is busy and cannot currently process your request. Try again later. |
| Unavailable (2) | A DSA is down so your request cannot be processed. |
| Unwilling To Perform (3) | A DSA is unwilling to process your request (no reason is given, tough luck). |
| Chaining Required (4) | Chaining is required in order to continue processing your request but you forbade it in your Service Controls. |
| Unable To Proceed (5) | The DSA you picked from those given to you in a referral was the wrong one. Try another. |
| Invalid Reference (6) | The DSA is not able to process your request as directed probably because you used information from an invalid referral. |
| Time Limit Exceeded (7) | The time you specified ran out before a result could be obtained. |
| Administrative Limit Exceeded (8) | Your request has caused a DSA limit set by its administrator to be exceeded. |
| Loop Detected (9) | The Directory has got an internal loop somewhere (probably an administrative error). |
| Unavailable Critical Extension (10) | You specified a critical extension that was not supported by the DSA processing your request. |
| Out Of Scope (11) | Referrals could not be returned to DSAs within the location you specified in your Service Controls (local domain or this country). |
| DIT Error (12) | There is a DIT consistency problem, such as a subordinate reference to nowhere! (Probably another administrative error.) |
| *Invalid Query Reference (13) | You returned the wrong query reference for the next page of results. |
The first two problems are primarily designed for replying to the Bind operation, the remainder are for the other operations.
Table 5.28 The parameters of the Security Error
| Security Error Problem (Code) | Meaning |
| Inappropriate Authentication (1) | The level of authentication provided by you was wrong e.g. the DSA wanted a protected password but you provided a plain one. |
| Invalid Credentials (2) | You provided the wrong password, or a forged signature. Naughty! |
| Insufficient Access Rights (3) | You do not have permission to access a requested entry. |
| Invalid Signature (4) | Your signed request contained an invalid signature. Naughty! |
| Protection Required (5) | You will need to send a signed request in order to carry out the requested operation. |
| No Information (6) | You have hit a sensitive DSA. It will not tell you what is wrong with your request. |
Table 5.29 The parameters of the Update Error
| Update Error Problem (Code) |
|
| Naming Violation (1) | You have attempted to name the entry in violation of the subschema DIT structure rules. |
| Object Class Violation (2) | You have attempted to modify the contents of the entry in violation of its object class(es) or DIT content rules. |
| Not Allowed On Non Leaf (3) | You have attempted an operation on a non-leaf entry that is only allowed on leaf entries e.g. to remove a non-leaf. |
| Not Allowed On RDN (4) | You have attempted a ModifyEntry operation on components of the RDN. |
| Entry Already Exists (5) | You have attempted to create an entry that already exists. |
| Affects Multiple DSAs (6) | Your update would cause more than one DSA to be involved and this is not supported by the implementation e.g. move entries to another DSA. |
| Object Class Modification Prohibited (7) | You attempted to modify the structural object class of the entry. This is not allowed! |
The rules state that DSAs shall ignore all unknown bits in a BIT STRING.
Note. All except the critical extensions BIT STRING (§ 5.20).
They shall ignore all unknown numbers in an ENUMERATED type (or equivalent integer type). They shall ignore all unknown tag values in sequences, sets and choices. Finally, DSAs should ignore all unknown error codes and problem codes.
This mechanism works fine when an old DSA is simply acting in a chaining mode between two newer DSAs. This is the case during the name resolution phase of a request, and also when passing a result or error back down the chain. The presence of new request parameters, or new result parameters or error codes should not affect the capacity of the DSA to simply relay the message. Merging of Search results from subordinate DSAs obviously poses a greater problem if unknown error codes or result parameters are returned. The former has been accommodated in the '93 edition of the Standard in order to cater for any new error codes that may subsequently be defined in later versions of the Standard (§ 5.8.2). The latter is not a problem if the parameters are embedded in individual Entry Information packages, since these are not unwrapped, but no solution (other than do not add new parameters to the Search result) has been suggested for the merging of unknown result parameters.
But what if the old DSA is meant to evaluate the operation? The rules still work if the extra parameters are only there to refine an operation, and are not crucial to its success. A DSA that does not understand the parameters will ignore them when processing the request. But what if this new parameter is critical, and radically affects the operation (for example, the new superior argument of the ModifyDN operation substantially changes the semantics of the operation)? An old DSA clearly cannot execute the operation as it was intended to be performed. Therefore the rules of extensibility are not sufficient on their own to ensure successful interworking between DSAs supporting different versions of the protocol. The critical extensions field, as described below, is there to solve this problem.
Attaching new semantics or rules to existing parameters still causes a problem, since an old DSA will not understand the new requirements, and can only operate with the old meanings. The rules for extensibility cannot help in this situation. Therefore a critical extension bit would have to be set to signify new semantics for old parameters. In fact, the '93 Standard has tried to avoid doing this, and none of these are currently defined.
One final area in which the rules for extensibility, or the critical extension bits cannot work, and this is when the extension affects name resolution. An old DSA has to ignore this sort of extension and perform name resolution according to the '88 Standard. Otherwise, if it understands the extension, then it is not an extension at all (by definition!) This has caused a problem with one extension, Use-Alias-On-Update (w/w 5.4).
Clearly the rules for extensibility have to be implemented by '88 DSAs in order for the scheme to work. But the rules were not defined in 1988. Therefore the rules have been agreed as a defect/omission in the '88 Standard. This means that '88 DSAs now have to support the rules if they wish to conform to the '88 Standard. If they do not implement them, they will be unable to operate freely with '93 implementations.
If a user (DUA) wishes to use an extension, but is not particularly bothered if the processing DSA(s) supports it or not, then the critical extensions bit can either be missing or set to zero. If the processing DSA, when parsing the request, understands the extra parameters that describe the extension, then the enhanced request will be executed. If it does not understand the parameters, then by following the rules for extensibility, it will simply ignore them when it processes the request. The user will receive the equivalent of an '88 evaluation.
If the user wishes to execute an enhanced operation, and the extension is critical to him, then the appropriate bit in critical extensions will be set to one. The processing DSA will now do one of two things. If it understands the semantics of the bit, and has implemented the extension, then it will give the user the enhanced level of service. If the DSA either does not understand the bit (because it was not defined in its edition of the Standard), or it understands the bit, but has not implemented the extension, then if the DSA is performing operation evaluation, the operation will be rejected. The user will receive a Service Error (Unavailable Critical Extension), since the DSA is unable to provide the critical level of service that the user required. If the DSA was performing name resolution, and it does not understand the critical extension, then it will ignore it and continue name resolution as normal. This is the reason why critical extensions should not be made to name resolution, since what is critical to the user may be ignored by the DSA (w/w 5.4). The Standard has therefore got it wrong with the Use-Alias-On-Update critical extension. The extension cannot be critical in all cases.
Apart from the above problem, the user is ultimately responsible for whether or not an enhanced level of service is given. Table 5.30 lists the definitions that have been attached to the first 11 bits of the critical extensions bit string.
Table 5.30 The Critical Extensions defined in the '93 Standard.
| Extension (bit) | Meaning | Used by Operation |
| Subentries (1) | The Access Subentries Service Control bit is set | List and Search |
| Copy Shall Do (2) | The Partial Copies of Entries Service Control bit is set | Read, Compare, List and Search |
| Attribute Size Limit (3) | The Maximum Attribute Size Service Control bit is set | Read and Search |
| Extra Attributes (4) | Selected Extra Attributes is present in Entry Information Selection | Read and Search |
| Modify Rights Request (5) | Tell Me My Modify Rights is set in the Read operation | Read |
| Paged Results Request (6) | Requesting Paged Results is present in the operation | List and Search |
| Matched Values Only (7) | The flag 'only attribute values matching the filter' is set | Search |
| Extended Filter (8) | Extensible Match is present in the filter and/or Additional filtering criteria are present in the operation | Search |
| Target System (9) | The DSA in which the entry is to be added is present | AddEntry |
| Use Alias On Update (10) | Aliases may be used and dereferenced | AddEntry. (RemoveEntry ??) and ModifyEntry |
| New Superior (11) | The New Superior argument is present in the operation | ModifyDN |
5.2 The Search operation is such a versatile operation that it is possible to present its arguments in such a way that it can perform the same request as any of the other interrogation operations. With such a versatile operation available to DUAs, one wonders why the Read, Compare, and List operations were ever defined in the first place. The answer was, of course, that this was not realised until after all the operations had been defined. It was then too late to remove them. The interested reader may wish to formulate Search requests with the same functionality as a Read, Compare and List operation.
5.3 The name of an operation is not actually carried in the protocol, instead each operation has been allocated a number (see footnote of 5.18). Thus '9' is understood by a '88 DSA to mean ModifyRDN, and by a '93 DSA to mean ModifyDN.
5.4 The critical extension scheme cannot work for the '93 extension that allows aliases to be used for update operations. If an update operation is routed via an '88 DSA to a '93 DSA, then the '88 DSA will only chain the request if it does not encounter an alias name in the purported name. If the name presented by the user goes via an alias in the '88 DSA, then the '88 DSA will fail the operation with Name Error (Alias Dereferencing Problem). '88 DSAs are not allowed to dereference aliases on update operations, and they ignore all critical extension bits during name resolution.
5.5 The Directory definition of two filter items (GreaterOrEqual and LessOrEqual) has caused some conflict with other OSI standards groups and users. The X.400 messaging group has identical filter item syntaxes, but with opposite meanings! This is because the X.400 semantics are 'presented value is less than or equal to attribute value', whereas the Directory semantics are 'attribute value is less than or equal to presented value'. Thus if an X.400 user specifies a filter less than or equal to, message size n, they will select messages of size n upwards. The Directory user, using the same filter, would select entries with message size attribute values of n or less. The X.400 group wanted the Directory group to change its definition to agree with theirs, but this was refused.
The DFR (document filing and retrieval) group import the Directory filter syntax, even though the Directory standard does not export it. A request from the DFR group to the Directory group, to export the filter construct, was refused by the Directory group, since the latter wanted to keep their freedom to change the filter at will without affecting other standards groups.
There have been several requests for new filter items of GreaterThan and LessThan to be defined, since the existing filter items cannot always give this capability. It is now possible to achieve this via the '93 ExtensibleMatch filter item, by defining new greater than and less than matching rules.
5.6 The ASN.1 parameter All User Attributes, was originally called All Attributes in the '88 Standard. Whilst the syntax, and hence the value carried in the protocol, has not changed between '88 and '93, the precise meaning of it has. This is to align with the expanded definition of 'attribute type' described in Chapter 2.
5.7 If we had been designing 'entry information selection' from scratch, we would not have designed it as described in 5.6.1. It would have simply been a picking list from All User Attributes, All Operational Attributes and a set of specifically named attributes. (A picking list in ASN.1 is a set of choice.) But because we had to be backwards compatible with the '88 Standard, which only allows one choice from two items (All User Attributes or a set of specifically named ones), this could not be done. Adding an extra item to the choice would still not have given us a picking list, but only one item from three. Hence the rather convoluted selection mechanism described in § 5.6.1.
5.8 One of the search arguments allows matched values only to be returned to the user from a multi-valued attribute. However, the equality filter item is excluded from this feature. In other words, if a value from a multi-valued attribute matched an equality filter item, all attribute values or none can be returned to the user (depending upon 'entry information selection'). If a value matched another filter item such as GreaterOrEqual, then no values, the matched value or all values can be returned to the user. In order to work around this 'quirk' of the Standard, the user would have to specify an 'extensible match' filter item, and quote the object identifier of the equality matching rule as the matching rule to be used. The filter would then perform equality matching, but would not have used the equality filter item, hence the matched value only could be returned.
