> ## Documentation Index
> Fetch the complete documentation index at: https://iso8583sim.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MACs

> ISO 9797-1 message authentication codes for ISO 8583 fields 64 and 128.

`iso8583sim.security.mac`

For testing and simulation only. Production MACs are generated inside an HSM.

## Functions

### `generate_mac()`

```python theme={null}
def generate_mac(
    data: str | bytes,
    key: str | bytes,
    algorithm: int = 3,
    padding: int = 1,
    length: int = 8,
) -> str
```

Generate an ISO 9797-1 MAC with DES based block ciphers.

Algorithm 1 is a CBC-MAC with the whole key (single, double or triple length).
Algorithm 3 is the retail MAC (ANSI X9.19): single DES CBC with the left key half,
then decrypt with the right half and encrypt with the left half on the final block.

**Parameters**

<ResponseField name="data" type="str | bytes" required>
  Data to authenticate. A str is encoded as ASCII, which is how this
  simulator carries ISO 8583 messages.
</ResponseField>

<ResponseField name="key" type="str | bytes" required>
  MAC key as bytes or hex (8, 16 or 24 bytes for algorithm 1; 16 for algorithm 3)
</ResponseField>

<ResponseField name="algorithm" type="int" default="3">
  ISO 9797-1 MAC algorithm: 1 or 3
</ResponseField>

<ResponseField name="padding" type="int" default="1">
  ISO 9797-1 padding method: 1 or 2
</ResponseField>

<ResponseField name="length" type="int" default="8">
  MAC length in bytes, 4 to 8. Truncation keeps the leftmost bytes.
</ResponseField>

<ResponseField name="Returns" type="str">
  The MAC as uppercase hex
</ResponseField>

### `verify_mac()`

```python theme={null}
def verify_mac(
    data: str | bytes,
    mac: str,
    key: str | bytes,
    algorithm: int = 3,
    padding: int = 1,
) -> bool
```

Check a MAC. The expected length is taken from the given MAC.

### `mac_field()`

```python theme={null}
def mac_field(fields: dict[int, str]) -> int
```

Return which field carries the MAC: 128 when the message has a secondary bitmap, else 64.

### `sign_message()`

```python theme={null}
def sign_message(
    message: ISO8583Message,
    key: str | bytes,
    builder: ISO8583Builder | None = None,
    algorithm: int = 3,
    padding: int = 1,
) -> str
```

Build a message with its MAC in field 64 (or 128 with a secondary bitmap).

**Parameters**

<ResponseField name="message" type="ISO8583Message" required>
  Message to build. Any existing MAC field is replaced.
</ResponseField>

<ResponseField name="key" type="str | bytes" required>
  MAC key as bytes or hex
</ResponseField>

<ResponseField name="builder" type="ISO8583Builder | None" default="None">
  Builder to use (defaults to one for the message's version)
</ResponseField>

<ResponseField name="algorithm" type="int" default="3">
  ISO 9797-1 MAC algorithm: 1 or 3
</ResponseField>

<ResponseField name="padding" type="int" default="1">
  ISO 9797-1 padding method: 1 or 2
</ResponseField>

<ResponseField name="Returns" type="str">
  The raw message with the MAC filled in
</ResponseField>

### `verify_message()`

```python theme={null}
def verify_message(
    raw: str,
    key: str | bytes,
    algorithm: int = 3,
    padding: int = 1,
    version: ISO8583Version | None = None,
) -> bool
```

Check the MAC in field 64 or 128 of a raw message built by this simulator.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.