15. Error Handling

This section defines standard error codes and error-handling requirements for the PALISADE protocol.

15.1 Error Message Format

When an error response is transmitted, it uses the following structure:

ErrorResponse =
    error_code   (2 bytes)
    details_len  (2 bytes)
    details      (details_len bytes)

Where:

• error_code is a 16-bit unsigned integer identifying the error condition.
• details is an OPTIONAL human-readable description.
• All multi-byte fields are encoded in big-endian byte order.

The details field is intended for diagnostics only and MUST NOT contain sensitive information.

15.2 Error Code Ranges

Error codes are divided into the following ranges:

15.3 Defined Error Codes

15.3.1 Handshake Errors (0x0100–0x01FF)

15.3.2 Session Errors (0x0200–0x02FF)

15.3.3 Data Plane Errors (0x0300–0x03FF)

15.3.4 Resumption Errors (0x0400–0x04FF)

15.3.5 Migration Errors (0x0500–0x05FF)

15.3.6 Control Frame Errors (0x0600–0x06FF)

15.3.7 Generic Errors (0xFF00–0xFFFF)

15.4 Fatal vs. Non-Fatal Errors

Errors are classified as fatal or non-fatal.

Fatal Errors

When a fatal error occurs, the endpoint MUST:

• Abort the current session or handshake.
• Securely erase all derived secrets.
• Cease further packet processing.
• Require a new handshake to resume communication.

An error response MAY be sent if doing so does not introduce additional risk.

Non-Fatal Errors

When a non-fatal error occurs, the endpoint:

• MAY continue processing subsequent packets.
• MUST NOT alter cryptographic session state unless explicitly required.

15.5 Error Transmission Rules

Error responses:

• MUST be encrypted if session keys are established.
• MAY be sent in cleartext only during the handshake, before keys are available.
• MUST NOT be retransmitted automatically.
• Endpoints MUST be robust to missing or dropped error responses.

15.6 Error Disclosure Policy

Error responses MUST NOT:

• Reveal cryptographic secrets.
• Reveal internal state, counters, or memory addresses.
• Enable oracle attacks through distinguishable behavior.

Implementations SHOULD minimize externally visible differences between error conditions.

15.7 Security Properties

The error framework ensures:

• Fail-closed behavior on cryptographic errors
• Resistance to oracle attacks
• Bounded information disclosure
• Clear separation between protocol and implementation policy