sansldap

https://sansldap.readthedocs.io/en/latest/
Admin
sansldap is an LDAP protocol stack written entirely in Python, designed around the Sans-IO model to...
Tokens:28,089
Snippets:171
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### push_set() example

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Use this snippet to start writing a SET or SET_OF value. The writer must be used within a with statement to ensure the sequence is closed and written back to the parent writer.

```python
with writer.push_set() as seq_writer:
    seq_writer.write_octet_string(b"foo")
```

--------------------------------

### Custom LDAPControl example

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Custom LDAPControl implementation that packs an integer size into a 4-byte value and unpacks it. Must inherit LDAPControl, set control_type, and implement get_value and unpack.

```python
@dataclasses.dataclass(frozen=True)
class CustomControl(LDAPControl):
    control_type: str = dataclasses.field(init=False, repr=False, default="1.2.3.4")
    value: t.Optional[bytes] = dataclasses.field(init=False, repr=False, default=None)

    size: int

    def get_value(
        self,
        options: ControlOptions,
    ) -> t.Optional[bytes]:
        return self.size.to_bytes(4)

    @classmethod
    def unpack(
        cls,
        control_type: str,
        critical: bool,
        value: t.Optional[bytes],
        options: ControlOptions,
    ) -> CustomControl:
        size = struct.unpack("<I", (value or b""))[0]

        return CustomControl(critical=critical, size=size)

```

--------------------------------

### data_to_send(amount=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Get data to send to the peer. Gets the data available in the outgoing buffer to send to the peer. If amount is not specified then the whole outgoing buffer is returned. Otherwise only the data up to the amount specified is returned.

```APIDOC
## data_to_send(amount=None)

### Description
Get data to send to the peer. Gets the data available in the outgoing buffer to send to the peer. If amount is not specified then the whole outgoing buffer is returned. Otherwise only the data up to the amount specified is returned.

### Parameters
- **amount** (`Optional`[`int`]) - Optional - The length of the output to return, otherwise all data will be returned if None.

### Returns
- **bytes** - The data to send to the peer.

```

--------------------------------

### Simple bind with sansldap

Source: https://sansldap.readthedocs.io/en/latest/events.html

Performs a simple bind with plaintext credentials. The example shows the client sending a BindRequest and the server responding with a BindResponse, including assertions on the request fields and the success result code. It also notes that a faulty bind can specify an error code.

```python
import sansldap

client = sansldap.LDAPClient()
server = sansldap.LDAPServer()

client.bind_simple("username", "password")
client_outgoing = client.data_to_send()

bind_request = server.receive(client_outgoing)[0]
assert isinstance(bind_request, sansldap.BindRequest)
assert isinstance(bind_request.authentication, sansldap.SimpleCredential)
assert bind_request.name == "username"
assert bind_request.authentication.password == "password"

# Can specify an error code on a faulty bind.
server.bind_response(bind_request.message_id)
server_outgoing = server.data_to_send()

bind_response = client.receive(server_outgoing)[0]
assert isinstance(bind_response, sansldap.BindResponse)
assert bind_response.result.result_code == sansldap.LDAPResultCode.SUCCESS

```

--------------------------------

### Search request with sansldap.LDAPClient and LDAPServer

Source: https://sansldap.readthedocs.io/en/latest/events.html

Performs a search request using sansldap.LDAPClient and sansldap.LDAPServer. The client sends a SearchRequest with an empty base object and the "defaultNamingContext" attribute; the server responds with a SearchResultEntry and a SearchResultDone. The example asserts the received messages and their contents, including the result code SUCCESS.

```python
import sansldap

client = sansldap.LDAPClient()
server = sansldap.LDAPServer()

# Client most likely needs to be bound before the search

# There are more options that can be provided for a request.
client.search_request("", attributes=["defaultNamingContext"])
client_outgoing = client.data_to_send()

search_request = server.receive(client_outgoing)[0]
assert isinstance(search_request, sansldap.SearchRequest)
assert search_request.base_object == ""
assert search_request.attributes == ["defaultNamingContext"]

server.search_result_entry(
    search_request.message_id,
    search_request.base_object,
    attributes=[
        sansldap.PartialAttribute("defaultNamingContext", [b"DC=domain,DC=test"]),
    ],
)
server.search_result_done(search_request.message_id)
server_outgoing = server.data_to_send()

responses = client.receive(server_outgoing)
assert len(responses) == 2
assert isinstance(responses[0], sansldap.SearchResultEntry)
assert isinstance(responses[1], sansldap.SearchResultDone)

assert len(responses[0].attributes) == 1
assert responses[0].attributes[0].name == "defaultNamingContext"
assert responses[0].attributes[0].values == [b"DC=domain,DC=test"]
assert responses[1].result.result_code == sansldap.LDAPResultCode.SUCCESS

```

--------------------------------

### Custom LDAPFilter example

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Custom LDAPFilter implementation that packs and unpacks a string value using ASN1Writer and ASN1Reader. Must inherit LDAPFilter, set filter_id, and implement pack and unpack. The filter must be understood by both client and server.

```python
@dataclasses.dataclass(frozen=True)
class CustomFilter(LDAPFilter):
    filter_id: int = dataclasses.field(init=False, repr=False, default=1024)

    value: str

    def pack(
        self,
        writer: sansldap.asn1.ASN1Writer,
        options: FilterOptions,
    ) -> None:
        writer.write_octet_string(
            self.value.encode(options.string_encoding),
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                self.filter_id,
                False,
            ),
        )

    @classmethod
    def unpack(
        cls,
        reader: sansldap.asn1.ASN1Reader,
        options: FilterOptions,
    ) -> CustomFilter:
        value = reader.read_octet_string(
            sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                cls.filter_id,
                False,
            ),
        ).decode("utf-8")
        return CustomFilter(value=value)

```

--------------------------------

### Custom AuthenticationCredential subclass with pack and unpack

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Shows how to implement a custom AuthenticationCredential subclass for use with sansldap.BindRequest. The example defines a frozen dataclass with a custom auth_id (1024) and implements pack and unpack methods that encode and decode a username:password string using the provided ASN.1 writer/reader and options. Both client and server must understand the custom credential.

```python
@dataclasses.dataclass(frozen=True)
class CustomAuth(a.AuthenticationCredential):
    auth_id: int = dataclasses.field(init=False, repr=False, default=1024)

    username: str
    password: str

    def pack(
        self,
        writer: sansldap.asn1.ASN1Writer,
        options: a.AuthenticationOptions,
    ) -> None:
        writer.write_octet_string(
            f"{self.username}:{self.password}".encode(options.string_encoding),
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                self.auth_id,
                False,
            ),
        )

    @classmethod
    def unpack(
        cls,
        reader: sansldap.asn1.ASN1Reader,
        options: a.AuthenticationOptions,
    ) -> CustomAuth:
        value = reader.read_octet_string(
            tag=sansldap.asn1.ASN1Tag(
                sansldap.asn1.TagClass.CONTEXT_SPECIFIC,
                cls.auth_id,
                False,
            ),
            hint="CustomAuth.value",
        ).decode(options.string_encoding)
        username, _, password = value.partition(":")

        return CustomAuth(username=username, password=password)

```

--------------------------------

### ASN1Writer.push_sequence

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

```APIDOC
## ASN1Writer.push_sequence

### Description
Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

### Method
push_sequence

### Parameters
- **tag** (`Optional[ASN1Tag]`) - Optional - Optional tag to mark the sequence/sequence_of with.

### Returns
ASN1Writer - The writer object that can be used to write the sequence elements.
```

--------------------------------

### ASN1Writer.push_sequence_of

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

```APIDOC
## ASN1Writer.push_sequence_of

### Description
Gets a new writer to start writing values inside a sequence or sequence of object. Make sure to wrap the writer in a with statement to ensure the sequence is closed and written back to the parent writer.

### Method
push_sequence_of

### Parameters
- **tag** (`Optional[ASN1Tag]`) - Optional - Optional tag to mark the sequence/sequence_of with.

### Returns
ASN1Writer - The writer object that can be used to write the sequence elements.

### Example
```
with writer.push_sequence() as seq_writer:
    seq_writer.write_octet_string(b"foo")
```
```

--------------------------------

### ASN1Writer.get_data

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Gets the data written to the writer. This is used to get the final ASN.1 value after all the values have been written to it.

```APIDOC
## ASN1Writer.get_data

### Description
Gets the data written to the writer. This is used to get the final ASN.1 value after all the values have been written to it. It cannot be called on a child writer returned by push_sequence or push_set.

### Method
get_data

### Returns
bytearray - The data that has been written.
```

--------------------------------

### search_request(base_object=None, scope=SearchScope.SUBTREE, dereferencing_policy=DereferencingPolicy.NEVER, size_limit=0, time_limit=0, types_only=False, filter=None, attributes=None, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a Search Request. Creates a search request that can result in three different responses: SearchResultEntry, SearchResultReference, and SearchResultDone. The operation is not complete until SearchResultDone is received.

```APIDOC
## search_request(base_object=None, scope=SearchScope.SUBTREE, dereferencing_policy=DereferencingPolicy.NEVER, size_limit=0, time_limit=0, types_only=False, filter=None, attributes=None, controls=None)

### Description
Send a Search Request. Creates a search request that can result in three different responses: SearchResultEntry, SearchResultReference, and SearchResultDone. The operation is not complete until SearchResultDone is received.

### Method
search_request

### Parameters
- **base_object** (`Optional[str]`) - Optional - The name of the base object entry, or None/empty string for root, which the search is to be performed.
- **scope** (`Union[int, SearchScope]`) - Optional - The scope of the search. Defaults to SUBTREE.
- **dereferencing_policy** (`Union[int, DereferencingPolicy]`) - Optional - Indicates how alias entries are to be dereferenced. Defaults to NEVER.
- **size_limit** (`int`) - Optional - The maximum number of entries to be returned. A value of 0 has no restrictions.
- **time_limit** (`int`) - Optional - The maximum time, in seconds, allowed for the operation. A value of 0 has no time restrictions.
- **types_only** (`bool`) - Optional - Only return attribute names and no values in the search result.
- **filter** (`Optional[LDAPFilter]`) - Optional - The LDAP filter to search by.
- **attributes** (`Optional[List[str]]`) - Optional - A list of attributes to be returned from each entry that match the search filter. The default requests the return of all user attributes.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- `int` - The message id associated with the request.

```

--------------------------------

### StartTLS operation with sansldap

Source: https://sansldap.readthedocs.io/en/latest/events.html

Performs a StartTLS operation using the sansldap library. It sends an ExtendedRequest with the LDAP_START_TLS operation, verifies the server's ExtendedResponse, and notes that the TLS handshake must be performed on the socket to wrap future messages.

```python
import sansldap

client = sansldap.LDAPClient()
server = sansldap.LDAPServer()

client.extended_request(sansldap.ExtendedOperations.LDAP_START_TLS.value)
client_outgoing = client.data_to_send()

ext_request = server.receive(client_outgoing)[0]
assert isinstance(ext_request, sansldap.ExtendedRequest)
assert ext_request.name == sansldap.ExtendedOperations.LDAP_START_TLS.value

server.extended_response(ext_request.message_id)
server_outgoing = server.data_to_send()

ext_response = client.receive(server_outgoing)[0]
assert isinstance(ext_response, sansldap.ExtendedResponse)
assert ext_response.result.result_code == sansldap.LDAPResultCode.SUCCESS

# The TLS handshake needs to be performed on the socket to set up the TLS
# channel. Any future messages to send from data_to_send() needs to be wrapped
# by the TLS channel that was set up.

```

--------------------------------

### LDAPServer

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

LDAP server session class for sending server LDAP messages.

```APIDOC
## LDAPServer

### Description
LDAP Server session class used to send server LDAP messages.

### Methods
#### bind_response(message_id, sasl_creds=None, result_code=LDAPResultCode.SUCCESS, matched_dn=None, diagnostics_message=None, controls=None)

Send a Bind Response. Responds to a bind request. The state will be changed to `OPENED` unless the result code is `SASL_BIND_IN_PROGRESS`.

##### Parameters
- **message_id** - Required - The message ID of the bind request.
- **sasl_creds** - Optional - SASL credentials.
- **result_code** - Optional - The result code to send. Defaults to `LDAPResultCode.SUCCESS`.
- **matched_dn** - Optional - The matched DN.
- **diagnostics_message** - Optional - The diagnostics message.
- **controls** - Optional - A list of controls.

```

--------------------------------

### bind_simple(dn=None, password=None, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a Simple BIND request for anonymous, unauthenticated, or authenticated bind. Returns the message id associated with the request.

```APIDOC
## bind_simple(dn=None, password=None, controls=None)

### Description
Send a Simple BIND request. Creates a SIMPLE bind request to perform an anonymous, unauthenticated, or authenticated bind. The format of dn depends on the LDAP server implementation.

### Method
BIND (Simple)

### Parameters
- **dn** (`Optional[str]`) - Optional - The name of the Directory object that the client wishes to bind as. Set to None or an empty string to perform an anonymous bind.
- **password** (`Optional[str]`) - Optional - The password to bind with, set to None or an empty string to perform an unauthenticated bind.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- **int** - The message id associated with the request.
```

--------------------------------

### Write a SEQUENCE with push_sequence()

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Use this snippet to write a SEQUENCE value. The writer must be used in a with statement to ensure the sequence is closed and written back to the parent writer.

```python
with writer.push_sequence() as seq_writer:
    seq_writer.write_octet_string(b"foo")

```

--------------------------------

### unpack(reader, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Unpacks raw bytes into a Python object using an ASN.1 reader.

```APIDOC
## unpack(reader, options)

### Description
Unpacks raw bytes into a Python object using an ASN.1 reader.

### Parameters
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is unpacked.

### Returns
An instance of the object that has been unpacked.

### Return Type
`LDAPFilter`
```

--------------------------------

### bind(dn, authentication, controls=None)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Sends a BIND request with a custom authentication credential. Returns the message id associated with the request.

```APIDOC
## bind(dn, authentication, controls=None)

### Description
Send a BIND request. Creates a bind request with the authentication payload specified. This can be used to bind with a custom set of credentials that have been registered with `LDAPSession.register_auth_credential()`. It is recommended to use `bind_simple()` or `bind_sasl()` instead of this function.

### Method
BIND

### Parameters
- **dn** (`str`) - Required - The name of the Directory object that the client wishes to bind as.
- **authentication** (`AuthenticationCredential`) - Required - The authentication object to bind with. This must be registered first with `LDAPSession.register_auth_credential()`.
- **controls** (`Optional[List[LDAPControl]]`) - Optional - Optional client controls to send with the request.

### Returns
- **int** - The message id associated with the request.
```

--------------------------------

### register_auth_credential(auth)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Register a custom authentication credential. Registers a custom `AuthenticationCredential` class that can be used for a bind.

```APIDOC
## register_auth_credential(auth)

### Description
Register a custom authentication credential. Registers a custom `AuthenticationCredential` class that can be used for a bind.

### Parameters
- **auth** (`Type`[`AuthenticationCredential`]) - Required - The custom authentication credential type to register.

### Returns
- **None**

```

--------------------------------

### unpack(reader, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Unpacks raw filter bytes into a Python object.

```APIDOC
## unpack(reader, options)

### Description
Unpacks the raw bytes into the Python object.

### Parameters
- **reader** (`ASN1Reader`) - Required - The reader used to read the ASN.1 data.
- **options** (`FilterOptions`) - Required - Options that can be used to control how the filter is unpacked.

### Returns
An instance of the object that has been unpacked.

### Return Type
`LDAPFilter`

```

--------------------------------

### pack(writer, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Packs the filter structure into an ASN.1 writer for embedding in a SearchRequest filter value.

```APIDOC
## pack(writer, options)

### Description
Packs the filter structure into an ASN.1 writer for embedding in a SearchRequest filter value.

### Parameters
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data.
- **options** (`FilterOptions`) - Required - Options controlling how the filter is packed.

### Return Type
`None`
```

--------------------------------

### pack(writer, options)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Packs the filter structure into an ASN.1 writer for embedding in a SearchRequest filter value.

```APIDOC
## pack(writer, options)

### Description
Packs the filter structure into the ASN.1 writer that is then embedded in the `SearchRequest` filter value. The tagged choice should also be included in the written value.

### Parameters
- **writer** (`ASN1Writer`) - Required - The writer used to write ASN.1 data
- **options** (`FilterOptions`) - Required - Options that can be used to control how the filter is packed.

### Return Type
`None`

```

--------------------------------

### receive(data)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Receives data from the peer and unpacks LDAP messages. Returns a list of complete LDAPMessage objects and buffers any remaining data internally. Raises ProtocolError on fatal parsing errors.

```APIDOC
## receive(data)

### Description
Receive data from the peer and unpack LDAP messages. Returns a list of complete LDAPMessage objects and buffers any remaining data internally. Raises ProtocolError on fatal parsing errors.

### Method
receive

### Parameters
- **data** (`Union[bytes, bytearray, memoryview]`) - Required - The data to process.

### Returns
- `t.List[LDAPMessage]` - A list of messages that have been unpacked.

### Raises
- **ProtocolError** - A protocol violation occurred and the connection is no longer valid.

```

--------------------------------

### register_control(control)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Register a custom LDAP control. Registers a custom `LDAPControl` class that can be used for controls in a request/response.

```APIDOC
## register_control(control)

### Description
Register a custom LDAP control. Registers a custom `LDAPControl` class that can be used for controls in a request/response.

### Parameters
- **control** (`Type`[`LDAPControl`]) - Required - The custom LDAP control type to register.

### Returns
- **None**

```

--------------------------------

### LDAPError

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Base LDAP error class. All LDAP-related exceptions derive from this class.

```APIDOC
## LDAPError

### Description
Base LDAP error class. All LDAP-related exceptions derive from this class.
```

--------------------------------

### receive(data)

Source: https://sansldap.readthedocs.io/en/latest/source/sansldap.html

Receive data to process. Receives the data from the peer and unpack the messages found into LDAPMessages. Any complete LDAP messages received will be returned and any remaining data will be stored in an internal buffer. A ProtocolError indicates something fatal has occurred when trying to parse the incoming data and the connection is no longer in a valid state.

```APIDOC
## receive(data)

### Description
Receive data to process. Receives the data from the peer and unpack the messages found into LDAPMessages. Any complete LDAP messages received will be returned and any remaining data will be stored in an internal buffer. A ProtocolError indicates something fatal has occurred when trying to parse the incoming data and the connection is no longer in a valid state. The caller SHOULD send the notice of disconnection payload available in `data_to_send()` and MUST close the underlying connection.

### Parameters
- **data** (`Union`[`bytes`, `bytearray`, `memoryview`]) - Required - The data to process.

### Returns
- **t.List[LDAPMessage]** - A list of messages that have been unpacked.

### Raises
- **ProtocolError** - A protocol violation occurred and the connection is no longer valid.

```
Tokens:
Raw