|
| 1 | +--- |
| 2 | +title: "Breaking change: LDAP DirectoryControl parsing is now more stringent" |
| 3 | +description: Learn about the .NET 10 breaking change in core .NET libraries where LDAP DirectoryControl parsing is now more stringent. |
| 4 | +ms.date: 01/30/2025 |
| 5 | +--- |
| 6 | + |
| 7 | +# LDAP DirectoryControl parsing is now more stringent |
| 8 | + |
| 9 | +Previously, .NET used <xref:System.DirectoryServices.Protocols.BerConverter?displayProperty=nameWithType> to parse the <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> objects it received over the network and to generate the <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> byte arrays it sent; <xref:System.DirectoryServices.Protocols.BerConverter?displayProperty=nameWithType> would use the OS-specific BER parsing functionality. This parsing functionality is now implemented in managed code. |
| 10 | + |
| 11 | +## Previous behavior |
| 12 | + |
| 13 | +As a result of using <xref:System.DirectoryServices.Protocols.BerConverter?displayProperty=nameWithType>, the parsing of <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> objects was fairly loose. |
| 14 | + |
| 15 | +- The ASN.1 tags of each value weren't checked. |
| 16 | +- Trailing data after the end of the parsed DirectoryControl was ignored, as was trailing data within an ASN.1 SEQUENCE. |
| 17 | +- On Linux, OCTET STRING lengths which extended beyond the end of their parent sequence would return data outside the parent sequence. |
| 18 | +- On earlier versions of Windows, a zero-length OCTET STRING would return `null` rather than an empty string. |
| 19 | +- When reading the contents of a <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> as a UTF8-encoded string, an invalid UTF8 sequence would not throw an exception. |
| 20 | +- When passing an invalid UTF8 string to the constructor of [VlvRequestControl](xref:System.DirectoryServices.Protocols.VlvRequestControl), no exception was thrown. |
| 21 | + |
| 22 | +While not a breaking change, Windows would always encode ASN.1 tags with a four-byte length while Linux would only use as many bytes for the tag length as it needed. Both representations were valid, but this behavioural difference between platforms is now gone; the Linux behaviour now also appears on Windows. |
| 23 | + |
| 24 | +## New behavior |
| 25 | + |
| 26 | +The DirectoryControl parsing is much more stringent, and is now consistent across platforms and versions. |
| 27 | + |
| 28 | +- ASN.1 tags are now checked. |
| 29 | +- Trailing data is no longer permitted. |
| 30 | +- The length of OCTET STRINGs and SEQUENCEs is now checked. |
| 31 | +- Zero-length OCTET STRINGs will now always return an empty string. |
| 32 | +- If the server sends an invalid UTF8 byte sequence, the <xref:System.DirectoryServices.Protocols.DirectoryControl?displayProperty=nameWithType> parsing logic will now throw an exception rather than silently substitute the invalid characters with a known value. |
| 33 | + |
| 34 | +We also validate errors more thoroughly when calling the VlvRequestControl constructor. Passing a string which cannot be encoded as a UTF8 value will now throw an EncoderFallbackException. |
| 35 | + |
| 36 | +## Version introduced |
| 37 | + |
| 38 | +.NET 10 Preview 1 |
| 39 | + |
| 40 | +## Type of breaking change |
| 41 | + |
| 42 | +This change is a [behavioral change](../../categories.md#behavioral-change). |
| 43 | + |
| 44 | +## Reason for change |
| 45 | + |
| 46 | +RFC/spec. compliance. In the various RFCs and sections of MS-ADTS, the controlValue is specified as the BER encoding of an ASN.1 structure with wording similar to the below (from [RFC2891, section 1.2](https://datatracker.ietf.org/doc/html/rfc2891#section-1.2)): |
| 47 | + |
| 48 | +> The controlType is set to "1.2.840.113556.1.4.474". The criticality is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value is the BER encoding of a value of the following SEQUENCE: |
| 49 | +
|
| 50 | +This precludes trailing data. It also rules out BER encodings of ASN.1 structures with differing ASN.1 tags, and of invalid BER encodings (such as OCTET STRINGs which are longer than their containing SEQUENCE.) |
| 51 | + |
| 52 | +For the VlvRequestControl constructor, throwing the exception early means that users can trust that only the values they explicitly specify are sent to the server - there are no circumstances where they can accidentally send `EF BF BD` to the server because they've passed a string which can't be encoded to valid UTF8 bytes. |
| 53 | + |
| 54 | +## Recommended action |
| 55 | + |
| 56 | +Servers should comply with the RFCs and specifications. Users should be aware of the need to handle an <xref:System.Text.EncoderFallbackException> when calling the <xref:System.DirectoryServices.Protocols.VlvRequestControl> constructor. |
| 57 | + |
| 58 | +## Affected APIs |
| 59 | + |
| 60 | +- <xref:System.DirectoryServices.Protocols.LdapConnection.SendRequest> |
| 61 | +- <xref:System.DirectoryServices.Protocols.LdapConnection.EndSendRequest> |
| 62 | +- <xref:System.DirectoryServices.Protocols.VlvRequestControl..ctor> |
0 commit comments