API Reference

exception icspacket.proto.mms.acse.ACSEAuthenticationFailure

Raised when ACSE authentication fails.

This typically occurs during association setup (AARQ/AARE exchange), if the peer rejects the provided credentials or the authentication mechanism is not recognized.

exception icspacket.proto.mms.acse.ACSEConnectionError

Base exception for ACSE-level failures.

Raised when association control messages (AARQ, AARE, ABRT, RLRQ, RLRE) cannot be successfully exchanged or processed. Subclasses distinguish between authentication failures, protocol negotiation errors, and other association-specific issues.

class icspacket.proto.mms.acse.Association(presentation: ISO_Presentation, pres_ctx_id: int | None = None, syntax_name: str | None = None, asn1_cls: type | None = None, authenticator: Authenticator | None = None)

Implements ACSE association management.

This class provides establishment, release, and abort of associations using the ACSE protocol (ISO 8650 / X.227). It operates on top of the Presentation service and ensures proper mapping of user data into the negotiated presentation context.

Example with MMS:

>>> pres = ISO_Presentation(...)
>>> assoc = Association(pres, MMS_PRESENTATION_CONTEXT_ID, MMS_ABSTRACT_SYNTAX_NAME, MMSpdu)
>>> assoc.create(("127.0.0.1", 1234))
<MMSpdu>

Parameters:

• presentation (ISO_Presentation) – Active presentation layer connection.

• pres_ctx_id (int | None) – Optional initial presentation context identifier.

• syntax_name (str | None) – Optional abstract syntax name for user data.

• asn1_cls (type | None) – ASN.1 type class bound to the context, if known.

property presentation: ISO_Presentation

Underlying presentation service bound to this ACSE association.

close() → None

Close the ACSE association and underlying presentation connection.

connect(address: tuple[str, int]) → None

Connect the underlying presentation service.

Parameters:

address (tuple[str, int]) – Remote address tuple (host, port).

create(address: tuple[str, int] | None = None, user_data: bytes | None = None, pres_ctx_id: int | None = None, syntax_name: str | None = None, application_context_name: str | None = None, asn1_cls: type | None = None) → bytes

Establish an ACSE association (AARQ/AARE exchange).

This method sends an Association Request (AARQ) and waits for an Association Response (AARE). On success, the association becomes valid and returns the negotiated user information.

Parameters:

• address (tuple[str, int] | None) – Optional remote address for initiating the session.

• user_data (bytes | None) – Optional user data to include in the AARQ.

• pres_ctx_id (int | None) – Presentation context identifier to use.

• syntax_name (str | None) – Application context name to negotiate.

• asn1_cls (type | None) – ASN.1 class for decoding user data.

Returns:

Associated user information payload.

Return type:

bytes

Raises:

• ACSEConnectionError – If association negotiation fails.

• ConnectionError – If already connected.

Note

Both pres_ctx_id and syntax_name must be provided, unless defaults are set using the constructor.

release(reason: VALUES | None = None, graceful: bool = False) → None

Release the ACSE association.

Sends a Release Request (RLRQ). Depending on graceful, this either allows an orderly release or immediately terminates.

Parameters:

• reason (Release_request_reason.VALUES, optional) – Reason code for release (default = normal).

• graceful (bool, optional) – If True, perform graceful closure; otherwise force.

Raises:

• ConnectionClosedError – If no release response is received in non-graceful mode.

• ACSEConnectionError – If an invalid response is returned.

abort(source: VALUES | None = None, user_data: bytes | None = None, pres_context_id: int | None = None) → None

Abort the ACSE association.

Immediately terminates the association by sending an Abort (ABRT) APDU. Optionally includes diagnostic info and user data.

Parameters:

• source (ABRT_source.VALUES, optional) – Abort initiator (default: ACSE service user).

• user_data (bytes, optional) – Optional encoded user data to send.

• pres_context_id (int, optional) – Context identifier for user data.

send_data(octets: bytes, /) → None

Send encoded user data via ACSE.

The data is wrapped into the negotiated presentation context.

Parameters:

octets (bytes) – Encoded ASN.1 payload.

Raises:

ConnectionNotEstablished – If no presentation context is bound.

recv_data() → bytes

Not supported.

Raw data reception is disallowed in ACSE. Use recv_encoded_data instead.

recv_encoded_data() → Any | None

Receive user data through ACSE association.

Retrieves encoded user information, decoding it according to the negotiated ASN.1 type for the active presentation context.

Returns:

Decoded user data instance or None.

Return type:

Any | None

Raises:

• ConnectionNotEstablished – If association has no context ID.

• ConnectionStateError – If no ASN.1 type is registered for the context.

class icspacket.proto.mms.acse.Authenticator

Abstract base class for ACSE authenticators.

Implementations are responsible for populating an AARQ-apdu with the appropriate authentication information (mechanism OID, tokens, AP-title/AE-qualifier if applicable).

Subclasses can implement different authentication mechanisms as specified in ISO 8650 (e.g., password).

abstractmethod prepare_association(aarq: AARQ_apdu) → None

Populate an AARQ-apdu with authentication credentials.

Parameters:

aarq (AARQ_apdu) – Association Request APDU to modify before sending to the peer.

Note

This method should not send the APDU itself, only update its authentication-related fields. The caller is responsible for encoding and transmission.

icspacket.proto.mms.acse.build_abort_request(source: VALUES, *, diagnostic: VALUES | None = None, user_data: bytes | None = None, presentation_context_id: int | None = None) → ABRT_apdu

Build an ACSE Abort Request (ABRT) APDU.

This creates an abort PDU for immediate termination of an ACSE association. It can optionally include diagnostic information and user data.

Parameters:

• source (ABRT_source.VALUES) – Identifies whether the abort was initiated by ACSE service user or provider.

• diagnostic (ABRT_diagnostic.VALUES | None) – Optional diagnostic code providing reason for abort.

• user_data (bytes | None) – Optional user data payload to include with the abort.

• presentation_context_id (int | None) – Context identifier for encoding user data.

Returns:

Encoded ACSE Abort APDU.

Return type:

ABRT_apdu

Raises:

ValueError – If user data is provided without a valid presentation context identifier.

icspacket.proto.mms.acse.build_associate_request(user_data: bytes, *, application_context_name: str | None = None, presentation_context_id: int | None = None, auth_mechanism_name: str | None = None, auth_token: Authentication_value | None = None) → AARQ_apdu

Build an ACSE Association Request (AARQ) APDU.

This constructs an AARQ PDU for establishing an ACSE association. Both the application-context-name and presentation-context-identifier must be supplied together; otherwise, defaults for MMS are applied.

Parameters:

• user_data (bytes) – Encoded user data payload.

• application_context_name (str | None) – Optional application context name.

• presentation_context_id (int | None) – Optional context identifier.

Returns:

Encoded ACSE Association Request APDU.

Return type:

AARQ_apdu

Raises:

ValueError – If only one of application_context_name or presentation_context_id is provided.

Note

If neither parameter is given, MMS defaults are used: MMS_CONTEXT_NAME and MMS_PRESENTATION_CONTEXT_ID.

icspacket.proto.mms.acse.build_release_request(reason: VALUES) → RLRQ_apdu

Build an ACSE Release Request (RLRQ) APDU.

This constructs a Release Request PDU according to ISO 8650 / X.227, which is used by an ACSE service user to signal the intention to terminate an established association.

Parameters:

reason (Release_request_reason.VALUES) – Release request reason (e.g., normal release).

Returns:

Encoded ACSE Release Request APDU.

Return type:

RLRQ_apdu

class icspacket.proto.mms.acse.PasswordAuth(password: str, ap_title: str, qualifier: int)

Annex B: Password-based authentication mechanism.

Implements the ACSE-defined password mechanism { joint-iso-itu-t(2) association-control(2) authentication-mechanism(3) password-1(1) }.

This authenticator inserts a cleartext password into the calling-authentication-value field of the AARQ-apdu, along with optional application entity identifiers.

Warning

Password authentication is considered weak and should generally only be used in test environments or legacy systems.

Parameters:

• password (str) – The cleartext password used for authentication.

• ap_title (str) – Application Process Title (AP-title) identifying the calling entity.

• qualifier (int) – Application Entity (AE) qualifier for the calling entity.

MECHANISM_NAME = '2.2.3.1'

Object identifier for ACSE password authentication.

ASN.1 notation: { joint-iso-itu-t(2) association-control(2) authentication-mechanism(3) password-1(1) }

property password: str

Returns:

The configured password.

Return type:

str

prepare_association(aarq: AARQ_apdu) → None

Populate the given AARQ-apdu with password-based authentication fields.

Sets the mechanism name to PasswordAuth.MECHANISM_NAME, inserts the password into calling-authentication-value, and fills in the calling-AP-title and calling-AE-qualifier.

Parameters:

aarq (AARQ_apdu) – Association Request APDU to modify.