Call this when creating a new cryptographic key — BDK, ZPK, CVK, MAC key, KEK, etc. Call explain_key_usage first to confirm the right key usage code — APC keys are typed at creation and the type cannot change.

AES keys must use CMAC for KCV (not ANSI_X9_24). Enforced here.

Args: key_algorithm: AES_128, AES_256, TDES_3KEY, RSA_2048, RSA_3072, RSA_4096, ECC_NIST_P256, etc. key_usage: TR-31 key usage code, e.g. TR31_P0_PIN_ENCRYPTION_KEY key_class: SYMMETRIC_KEY, ASYMMETRIC_KEY_PAIR, or PRIVATE_KEY exportable: Whether the key can be exported via TR-31 or TR-34 enabled: Whether the key is immediately active (default true) key_check_value_algorithm: CMAC, ANSI_X9_24, HMAC, or SHA_1. AES keys must use CMAC (ANSI_X9_24 is rejected here per PCI PIN Annex C); TDES may use either. HMAC keys use HMAC — the construction is fixed but the hash is the one bound to the key at creation, over a zero-length message, so reproducing the KCV outside APC requires knowing that hash. Asymmetric keys use SHA_1. tags: Optional list of {Key, Value} tag dicts derive_key_usage: For a BDK (B0) only — the TR-31 usage the derived DUKPT working keys will carry, e.g. TR31_P0_PIN_ENCRYPTION_KEY. APC binds this at creation, so a BDK created without it cannot later derive keys of that usage. replication_regions: Optional list of regions to replicate this key into, e.g. ["us-west-2", "eu-west-1"]. Omit to use the account default (see get_default_key_replication_regions). Replication is a property of the key, so set it here or via add_key_replication_regions afterwards.

Call this when you need the current state, algorithm, usage, or enabled status of a key before using it in an operation.

Retrieve metadata for a key by ARN or alias.

Args: key_identifier: Key ARN (arn:aws:payment-cryptography:...) or alias (alias/name)

Call this when auditing which keys exist, finding a key ARN, or checking key state before an import or operation.

List APC keys with optional state filter.

Args: key_state: CREATE_COMPLETE, CREATE_IN_PROGRESS, DELETE_PENDING, DELETE_COMPLETE max_results: Max keys to return (1-100) next_token: Pagination token from a previous response

Call this when decommissioning a test key or retiring a key that is no longer needed. Deletion is scheduled — the key enters DELETE_PENDING state first.

Schedule a key for deletion.

Args: key_identifier: Key ARN or alias delete_key_in_days: Waiting period before deletion (3-180 days, default 7)

Call this when a key was scheduled for deletion by mistake and needs to be recovered before the waiting period expires.

Cancel a pending key deletion.

Args: key_identifier: Key ARN or alias in DELETE_PENDING state

Call this when enabling a key that was created with enabled=False or that was previously disabled with stop_key_usage.

Activate a key that was created in disabled state.

Args: key_identifier: Key ARN or alias

Call this when temporarily disabling a key — for example during key rotation before the old key is confirmed unused and can be deleted.

Deactivate a key without deleting it.

Args: key_identifier: Key ARN or alias

Call this to make an existing key usable from additional regions — e.g. standing up a DR region, or moving an acquirer workload closer to the processor.

Replication copies the key into the named regions so cryptographic calls can be served there. It does not export key material: the key never leaves APC's HSMs, and the replica keeps the same key ARN semantics and usage restrictions.

Args: key_identifier: ARN or alias of the key replication_regions: Regions to add, e.g. ["us-west-2", "eu-west-1"]

Call this when decommissioning a region or narrowing a key's blast radius.

Removing a region makes the key unusable there. Confirm nothing is still authorizing against it in that region first — in-flight PIN or ARQC traffic will start failing as soon as the replica is gone.

Args: key_identifier: ARN or alias of the key replication_regions: Regions to remove, e.g. ["eu-west-1"]

Call this to see which regions new keys replicate into by default, before creating keys or when auditing why a key landed in a region you did not expect.

Keys created or imported without an explicit replication_regions inherit this account-level default.

Call this to add regions to the account-wide default, so subsequently created keys replicate there automatically.

This is account-level and affects future keys only — it does not retroactively replicate existing keys. Use add_key_replication_regions for keys that already exist.

Args: replication_regions: Regions to enable by default, e.g. ["us-west-2"]

Call this to stop new keys from automatically replicating into the named regions.

Account-level and forward-looking only: existing keys keep whatever replication they already have. Use remove_key_replication_regions to change those.

Args: replication_regions: Regions to remove from the default, e.g. ["eu-west-1"]

Call this when establishing a stable name for a key so application code does not need to change when keys are rotated.

Create a friendly-name alias for a key.

Args: alias_name: Must start with 'alias/' — e.g. alias/prod-bdk key_arn: Key ARN to associate (optional at creation time)

Call this when resolving an alias to its key ARN, or verifying which key an alias currently points to.

Retrieve alias details.

Args: alias_name: Full alias name including 'alias/' prefix

Call this when rotating a key — point the existing alias to the new key ARN so application code referencing the alias picks up the rotation automatically.

Point an alias to a different key (enables key rotation without code changes).

Args: alias_name: Full alias name including 'alias/' prefix key_arn: New key ARN to associate

Call this when removing a friendly name that is no longer needed. The underlying key is unaffected.

Delete an alias (does not delete the underlying key).

Args: alias_name: Full alias name including 'alias/' prefix

Call this when auditing all friendly names in the account, or finding aliases associated with a specific key.

List aliases, optionally filtered by key ARN.

Args: key_arn: Filter to aliases associated with this key max_results: Max results (1-100) next_token: Pagination token

Call this before import_key when using TR-34 or KeyCryptogram — you need APC's public wrapping key and import token before constructing the import payload.

Key-strength rules enforced by APC (wrapping key strength ≥ working key strength): AES-128 (128-bit): RSA_3072 (~128-bit) or RSA_4096 (~140-bit) — both acceptable. AES-256 (256-bit): RSA of any size is too weak (~140-bit max for RSA_4096). Use ECC_NIST_P521 (~261-bit) — the only KEY_CRYPTOGRAM path for AES-256. TDES (112-bit): RSA_2048 (~112-bit) or higher.

For AES-256 keys (E0, E1, E2, E4, E6, D0 at 256-bit, M6 at 256-bit): wrapping_key_algorithm must be ECC_NIST_P521. Attempting RSA_2048/RSA_3072/RSA_4096 with an AES-256 key will fail. Alternative: use create_key (APC generates the key material — no import needed, but the key value is not externally known, so cross-system test vectors are not possible).

Args: key_material_type: KEY_CRYPTOGRAM, Tr34KeyBlock, Tr31KeyBlock, RootCertificatePublicKey, or TrustedCertificatePublicKey wrapping_key_algorithm: RSA_2048, RSA_3072, RSA_4096, or ECC_NIST_P521 (required for AES-256) reuse_last_generated_token: Reuse the existing import token and wrapping key certificate when one is still valid for the same key material type and algorithm, with at least 7 days of validity left. Default false, which mints a new token on every call. Set true when retrying, or when building an import payload across several steps, so the token does not change underneath you.

Call this before export_key when using TR-34 — you need APC's signing certificate before constructing the export payload for an external system.

Args: key_material_type: Tr31KeyBlock or Tr34KeyBlock signing_key_algorithm: RSA_2048, RSA_3072, RSA_4096 reuse_last_generated_token: Reuse the existing export token and signing key certificate when one is still valid for the same key material type and algorithm, with at least 7 days of validity left. Default false, which mints a new token on every call. Set true when retrying, or when building an export payload across several steps, so the token does not change underneath you.

Call this to bring an externally generated key into APC via TR-31 key block or TR-34. The key_material dict structure depends on the import method.

IMPORTANT — this call does not always mean the key is imported. If the account has Multi-Party Approval associated with the import operation (see get_mpa_team_association), the response carries an MpaStatus with Status PENDING and the key is NOT yet usable. Approval by the MPA team has to land first. Treat a successful response as "submitted", not "done": check MpaStatus before using the key or reporting the import as complete, and poll get_key until the status clears. A response with no MpaStatus is an ordinary immediate import.

For TR-31 (wrapping an existing key): key_material = { "Tr31KeyBlock": { "WrappingKeyIdentifier": "", "WrappedKeyBlock": "" } }

For TR-34 (distributing a symmetric key using asymmetric techniques): key_material = { "Tr34KeyBlock": { "CertificateAuthorityPublicKeyIdentifier": "", "ImportToken": "", "KeyBlockFormat": "X9_TR34_2012", "WrappingKeyCertificate": "", "SigningKeyCertificate": "", "EncryptedKeyBlock": "" } }

Args: key_material: Import method and wrapped key material key_check_value_algorithm: CMAC, ANSI_X9_24, HMAC, or SHA_1. AES keys must use CMAC (ANSI_X9_24 is rejected here per PCI PIN Annex C); TDES may use either. HMAC keys use HMAC — the construction is fixed but the hash is the one bound to the key at creation, over a zero-length message, so reproducing the KCV outside APC requires knowing that hash. Asymmetric keys use SHA_1. enabled: Activate key immediately after import tags: Optional list of {Key, Value} tag dicts replication_regions: Optional list of regions to replicate the imported key into. Omit to use the account default (see get_default_key_replication_regions). requester_comment: Optional reason for the import, max 200 characters. Shown to Multi-Party Approval reviewers when the import is gated. Appears in CloudTrail in plaintext — no personal or sensitive data.

Call this when distributing an APC-generated key to an external HSM or system, wrapped in a TR-31 key block, a TR-34 structure, an RSA cryptogram, an ECDH-derived key block, or an AS2805 cryptogram.

key_material is a single-member union naming the export method. The wrapping material lives inside it — unlike import_key, there is no separate "type" argument:

{"Tr31KeyBlock": {"WrappingKeyIdentifier": ""}}

{"Tr34KeyBlock": {"CertificateAuthorityPublicKeyIdentifier": "", "WrappingKeyCertificate": "", "KeyBlockFormat": "X9_TR34_2012", "ExportToken": ""}}

{"KeyCryptogram": {"CertificateAuthorityPublicKeyIdentifier": "", "WrappingKeyCertificate": "", "WrappingSpec": "RSA_OAEP_SHA_256"}}

{"DiffieHellmanTr31KeyBlock": {...}} ECDH-derived; needed for AES-192/256 {"As2805KeyCryptogram": {...}} AS2805 (Australian standard)

Args: export_key_identifier: ARN or alias of the key to export key_material: Single-member union selecting the export method, see above export_attributes: Optional. ExportDukptInitialKey (for IPEK export) and/or KeyCheckValueAlgorithm.

Call this to get a PKCS #10 CSR for an APC-held asymmetric key, so an external CA (or a partner's PKI) can issue a certificate for it. This is the APC counterpart of the payShield/Futurex "generate certificate request" commands — Futurex RSAR, for instance, is a PKCS #10 CSR generator.

The private key stays in APC's HSMs; only the CSR leaves. Typical use is TR-34 key distribution or ECDH key exchange, where the counterparty must trust an APC key.

Args: key_identifier: ARN or alias of the asymmetric key (RSA or ECC) to request a certificate for signing_algorithm: Hash used to sign the CSR — SHA224, SHA256, SHA384, or SHA512 certificate_subject: X.509 subject. CommonName is required; OrganizationUnit, Organization, City, Country, StateOrProvince and EmailAddress are optional: {"CommonName": "acquirer-tr34-2026", "Organization": "Example Bank", "Country": "US"}

Call this to fetch the certificate and chain for an APC asymmetric key — to hand a counterparty the public half for TR-34 or ECDH key exchange, or to check what APC currently holds for a key.

Returns KeyCertificate and KeyCertificateChain, both base64-encoded. Public material only; no private key is ever returned.

Args: key_identifier: ARN or alias of the asymmetric key

Call this when adding classification, environment, or ownership metadata to a key.

Add or update tags on an APC key.

Args: resource_arn: Key ARN tags: List of {Key, Value} dicts

Call this when removing stale or incorrect tags from a key.

Remove tags from an APC key.

Args: resource_arn: Key ARN tag_keys: List of tag key names to remove

Call this when auditing the tags on a key or verifying classification metadata.

List all tags on an APC key.

Args: resource_arn: Key ARN max_results: Max results (1-100) next_token: Pagination token

Call this when granting cross-account access to a key or restricting which principals may use it.

Attach an IAM resource policy to a key.

Args: resource_arn: Key ARN policy: JSON policy document string

Call this when auditing who has access to a key or inspecting a cross-account policy.

Retrieve the resource policy attached to a key.

Args: resource_arn: Key ARN

Call this when revoking all cross-account or resource-based access grants on a key.

Remove the resource policy from a key.

Args: resource_arn: Key ARN

Call this to put a sensitive key-management operation behind Multi-Party Approval, so it requires sign-off from an AWS MPA approval team before it takes effect.

This is the APC equivalent of the dual-control requirement PCI PIN places on key management: no single custodian can complete the operation alone. Associating a team does not itself need approval; it changes how the named operation behaves from then on.

Once associated, calls to the covered operation return with an MpaStatus of PENDING rather than completing. See import_key for what that means in practice.

Args: action: The operation to protect. Currently only IMPORT_ROOT_PUBLIC_KEY_CERTIFICATE is supported by APC. mpa_team_arn: ARN of the AWS Multi-Party Approval team, of the form arn:aws:mpa:::approval-team/ requester_comment: Optional reason for the change, max 200 characters. Appears in CloudTrail in plaintext — no sensitive data.

Call this to remove Multi-Party Approval from an operation, returning it to single-principal control.

This weakens a dual-control boundary, so it is worth confirming intent before calling — under PCI PIN, removing dual control from key management is a compliance-relevant change, not a routine configuration tweak.

The association moves to DELETE_PENDING and may itself require approval from the currently associated team before it clears.

Args: action: The operation to stop protecting, e.g. IMPORT_ROOT_PUBLIC_KEY_CERTIFICATE requester_comment: Optional reason, max 200 characters. Plaintext in CloudTrail.

Call this to check whether an operation is under Multi-Party Approval, which team approves it, and whether a change to that association is still settling.

Use it before an import that may be gated, and when auditing dual control.

Returns MpaTeamAssociation with: Action — the protected operation MpaTeamArn — the approving team AssociationState — ACTIVE, UPDATE_PENDING, or DELETE_PENDING MpaStatus — present when an approval session is in flight, carrying MpaSessionArn, Status (PENDING / APPROVED / FAILED / CANCELLED) and InitiationDate

Args: action: The operation to inspect, e.g. IMPORT_ROOT_PUBLIC_KEY_CERTIFICATE

Call this whenever a TR-31 key usage code appears or someone asks "which key type should I use for X?" — P0, B0, E0, E1, E2, M6, C0, V1, V2, K0, K1, D0, etc. Works without AWS credentials.

Returns what the key type is, what operations it permits, which APC data-plane calls accept it, and any PCI compliance considerations.

Args: key_usage: TR-31 key usage code, e.g. TR31_P0_PIN_ENCRYPTION_KEY

Call this when designing key infrastructure, selecting key types for a new payment operation, or when asked what key types APC supports. Works without AWS credentials.

Returns all TR-31 key usage codes with names, descriptions, and APC support status.

Call this when encrypting cardholder data, PIN blocks, or sensitive payment fields for storage or transmission. Also use when implementing DUKPT session encryption or EMV session-key-based data confidentiality.

Supported key types: D0 (symmetric), D1 (asymmetric RSA), B0 (DUKPT), E1/E6 (EMV). All inputs and outputs are hexBinary encoded.

encryption_attributes examples: Symmetric AES-CBC: {"Symmetric": {"Mode": "CBC", "InitializationVector": "<16-byte hex>"}} DUKPT AES: {"Dukpt": {"KeySerialNumber": "", "Mode": "CBC", "DukptKeyDerivationType": "AES_128"}} EMV: {"Emv": {"MajorKeyDerivationMode": "EMV_OPTION_A", "PrimaryAccountNumber": "...", "PanSequenceNumber": "01", "SessionDerivationData": "...", "Mode": "CBC"}}

wrapped_key (dynamic key — TR-31 key block passed directly): {"WrappedKeyMaterial": {"Tr31KeyBlock": ""}, "KeyCheckValueAlgorithm": "CMAC"}

Args: key_identifier: Key ARN or alias of the KEK (when using wrapped_key) or the working key plain_text: Hex-encoded plaintext to encrypt encryption_attributes: Algorithm-specific parameters dict wrapped_key: Optional TR-31 wrapped working key (key_identifier becomes the KEK)

Call this when decrypting cardholder data or payment fields received from a terminal, acquiring host, or issuer — including DUKPT session-key decryption and EMV confidentiality decryption.

Supported key types: D0, D1, B0 (DUKPT), E1/E6 (EMV). All inputs and outputs are hexBinary encoded.

Args: key_identifier: Key ARN or alias of the KEK (when using wrapped_key) or the working key cipher_text: Hex-encoded ciphertext decryption_attributes: Algorithm-specific parameters (mirrors encrypt_data) wrapped_key: Optional TR-31 wrapped working key (key_identifier becomes the KEK)

Call this when rewrapping payment data under a new key — for example when rotating zone encryption keys, moving data between security domains, or transitioning from TDES to AES. The plaintext never leaves the HSM boundary.

Re-encrypts data from one key to another without exposing plaintext. The decryption and re-encryption occur entirely within the APC HSM boundary.

Args: incoming_key_identifier: ARN or alias of the current encryption key (or KEK) outgoing_key_identifier: ARN or alias of the target encryption key (or KEK) cipher_text: Hex-encoded ciphertext under the incoming key incoming_encryption_attributes: Algorithm params for decryption outgoing_encryption_attributes: Algorithm params for re-encryption incoming_wrapped_key: Optional TR-31 wrapped incoming working key outgoing_wrapped_key: Optional TR-31 wrapped outgoing working key

Call this when implementing acquirer PIN routing, verifying a PIN translation flow, or checking whether a given format-to-format translation is legal under PCI PIN. This is the core HSM operation in every acquiring PIN path.

Translates a PIN block between encryption zones inside the APC HSM boundary — the PIN is never exposed in clear text. Compliance rules are enforced:

• PAN must not change between incoming and outgoing formats (PCI PIN Req 3-3)

• Only legal ISO 9564 format translations are permitted (Req 3-3)

• Fixed TDES PIN keys are prohibited since 1 January 2023 (Req 2-2)

Preferred flow: AES DUKPT (Format 4) inbound → ZPK AES (Format 4 or 0) outbound

incoming_translation_attributes examples: ISO Format 4 (AES): {"IsoFormat4": {"PrimaryAccountNumber": "1712345678901234"}} ISO Format 0 (TDES): {"IsoFormat0": {"PrimaryAccountNumber": "1712345678901234"}} AS2805 Format 0: {"As2805Format0": {"PrimaryAccountNumber": "1712345678901234"}}

incoming_dukpt_attributes (when incoming key is a BDK): {"KeySerialNumber": "<10 or 12 byte KSN hex>"}

incoming_as2805_attributes (when incoming block uses AS2805 format): {"SessionKeyDerivationAttributes": {...}}

incoming_wrapped_key / outgoing_wrapped_key (dynamic key — TR-31 block passed directly): {"WrappedKeyMaterial": {"Tr31KeyBlock": ""}, "KeyCheckValueAlgorithm": "CMAC"}

Args: incoming_key_identifier: ARN or alias of inbound PEK or BDK (or KEK for wrapped key) outgoing_key_identifier: ARN or alias of outbound PEK or BDK (or KEK for wrapped key) incoming_translation_attributes: PIN block format and PAN for inbound outgoing_translation_attributes: PIN block format and PAN for outbound encrypted_pin_block: Hex-encoded encrypted PIN block incoming_dukpt_attributes: Required when incoming key is a BDK (DUKPT) outgoing_dukpt_attributes: Required when outgoing key is a BDK (DUKPT) incoming_as2805_attributes: Required when incoming block uses AS2805 format incoming_wrapped_key: Optional TR-31 wrapped incoming PEK outgoing_wrapped_key: Optional TR-31 wrapped outgoing PEK

Call this when implementing IBM 3624 or Visa PVV PIN generation, generating a PIN offset for card personalization, or producing a test PIN block for a given PAN. Issuer function — use with care in acquirer contexts.

Supported schemes via generation_attributes: Visa PVV: {"VisaPin": {"PinVerificationKeyIndex": 1}} Visa PVV value: {"VisaPinVerificationValue": {"EncryptedPinBlock": "...", "PinVerificationKeyIndex": 1}} IBM3624 offset: {"Ibm3624PinOffset": {"DecimalizationTable": "...", "PinValidationData": "..."}} IBM3624 random: {"Ibm3624RandomPin": {"DecimalizationTable": "..."}} IBM3624 natural: {"Ibm3624NaturalPin": {"DecimalizationTable": "..."}} IBM3624 from offset: {"Ibm3624PinFromOffset": {"DecimalizationTable": "...", "PinOffset": "...", "PinValidationData": "..."}}

Supported key types: generation_key_identifier: V1 (IBM3624) or V2 (Visa) PVK encryption_key_identifier: P0 PIN Encryption Key (or KEK when using encryption_wrapped_key)

primary_account_number is optional for ISO_FORMAT_1 (which does not include PAN).

Args: generation_key_identifier: ARN or alias of PVK (V1 or V2 key) encryption_key_identifier: ARN or alias of PEK (P0 key) to encrypt output PIN block generation_attributes: Scheme-specific generation parameters pin_block_format: ISO_FORMAT_0, ISO_FORMAT_1, ISO_FORMAT_3, or ISO_FORMAT_4 primary_account_number: 12-19 digit PAN (required for all formats except ISO_FORMAT_1) pin_data_length: PIN length (4-12); omit to use scheme default encryption_wrapped_key: Optional TR-31 wrapped PEK (encryption_key_identifier becomes the KEK)

Call this when implementing PIN verification at an issuer host — checking a cardholder-entered PIN against a stored IBM 3624 offset or Visa PVV. Also use to validate PIN verification logic end-to-end before deploying to production.

Verify a cardholder PIN against a stored PIN verification value.

Supported key types: verification_key_identifier: V1 (IBM3624) or V2 (Visa) PVK encryption_key_identifier: P0 PIN Encryption Key or B0 BDK (DUKPT)

primary_account_number is optional for ISO_FORMAT_1 (which does not include PAN).

dukpt_attributes (when encryption_key_identifier is a BDK): {"KeySerialNumber": "", "DukptKeyDerivationType": "AES_128"}

Args: verification_key_identifier: ARN or alias of PVK encrypted_pin_block: Hex-encoded encrypted PIN block encryption_key_identifier: ARN or alias of PEK or BDK (or KEK for wrapped key) verification_attributes: Scheme-specific verification params (mirrors generate_pin_data) pin_block_format: ISO_FORMAT_0, ISO_FORMAT_1, ISO_FORMAT_3, or ISO_FORMAT_4 primary_account_number: 12-19 digit PAN (required for all formats except ISO_FORMAT_1) pin_data_length: Optional PIN length override dukpt_attributes: Required when encryption_key_identifier is a BDK encryption_wrapped_key: Optional TR-31 wrapped PEK (encryption_key_identifier becomes the KEK)

Call this when implementing card personalization, CVV/CVV2/iCVV generation, or validating card data for testing. Also use to generate test vectors for CVK-based validation before writing production code.

Generates CVV, CVV2, iCVV, or dynamic card verification values. Supported key types: C0 (CVK), E4/E6 (EMV).

generation_attributes examples: CVV: {"CardVerificationValue1": {"CardExpiryDate": "0128", "ServiceCode": "101"}} CVV2: {"CardVerificationValue2": {"CardExpiryDate": "0128"}} iCVV: {"CardVerificationValue1": {"CardExpiryDate": "0128", "ServiceCode": "999"}} ARQC: {"DynamicCardVerificationCode": {"ApplicationTransactionCounter": "0001", "PanSequenceNumber": "01", "TrackData": "..."}}

Args: key_identifier: ARN or alias of CVK (C0) or EMV key primary_account_number: 12-19 digit PAN generation_attributes: Algorithm and card data parameters validation_data_length: Optional output length override

Call this when validating a card presented at POS or in CNP — verifying a CVV, CVV2, or iCVV value against the issuer's CVK. Also use to test CVK-based validation before writing production card-present or card-not-present logic.

Verify card validation data (CVV, CVV2, iCVV, dynamic values).

Supported key types: C0 (CVK), E4/E6 (EMV).

Args: key_identifier: ARN or alias of CVK or EMV key primary_account_number: 12-19 digit PAN verification_attributes: Algorithm and card data (mirrors generate_card_validation_data) validation_data: The CVV/CVV2/iCVV value to verify

Call this when implementing or validating MAC generation for ISO 8583 transactions, EMV issuer scripts, or any payment message authentication. Also call to verify which MAC algorithm a given M-key type supports before writing code.

Preferred key type: M6 (CMAC). Legacy: M1 (CBC-MAC), M3 (Retail MAC), M0 (AS2805). ISO 8583 field 64 (primary MAC) or field 128 (secondary MAC).

generation_attributes examples: CMAC: {"Algorithm": "CMAC"} ISO 9797-1 Alg 1 (CBC-MAC): {"Algorithm": "ISO9797_ALGORITHM1"} ISO 9797-1 Alg 3 (Retail): {"Algorithm": "ISO9797_ALGORITHM3"} HMAC-SHA256: {"Algorithm": "HMAC_SHA256"} DUKPT CMAC (AES): {"DukptCmac": {"KeySerialNumber": "...", "DukptKeyVariant": "BIDIRECTIONAL", "DukptDerivationType": "AES_128"}} DUKPT Alg 1 (3DES): {"DukptIso9797Algorithm1": {"KeySerialNumber": "...", "DukptKeyVariant": "REQUEST", "DukptDerivationType": "TDES_2KEY"}} DUKPT Alg 3 (3DES): {"DukptIso9797Algorithm3": {"KeySerialNumber": "...", "DukptKeyVariant": "REQUEST", "DukptDerivationType": "TDES_2KEY"}}

DUKPT key variant rules: BIDIRECTIONAL is only valid for AES DUKPT (DukptDerivationType: AES_128/AES_192/AES_256). For 3DES DUKPT (TDES_2KEY/TDES_3KEY) use REQUEST (terminal→host) or RESPONSE (host→terminal). Passing BIDIRECTIONAL with a TDES derivation type returns ValidationException.

CMAC mac_length note: generate_mac with CMAC always returns the full 16-byte (32H) MAC regardless of the mac_length parameter — APC returns the full value and the caller truncates. If you need verify_mac to accept a truncated CMAC (e.g. 4-byte / 8H from a payShield M8 flow), see verify_mac docstring for the workaround.

Args: key_identifier: ARN or alias of MAC key (M0, M1, M3, M6, or M7) message_data: Hex-encoded message to authenticate generation_attributes: MAC algorithm parameters mac_length: Output MAC length in nibbles/hex-digits (NOT bytes): 8=4-byte MAC, 16=8-byte MAC; omit for algorithm default

Call this to verify a MAC on a received payment message or issuer script. Mirrors generate_mac — use the same algorithm and key.

CMAC truncation warning: verify_mac with CMAC requires the FULL MAC value (16 bytes / 32H for AES-128). Passing a truncated CMAC — e.g. 4 bytes / 8H produced by payShield M6 with mac_size=0 — returns ValidationException with no descriptive error message. ISO 9797-1 Alg 1/3 produce 4-byte MACs natively and are not affected.

Workaround for truncated CMAC verify (e.g. bridging a payShield M8 flow):

1. Call generate_mac with the same key and message.

2. Compare the leading mac_length bytes of the returned 32H MAC against the received value. This costs one extra APC call per verify.

Args: key_identifier: ARN or alias of MAC key message_data: Hex-encoded message that was authenticated mac: Hex-encoded MAC value to verify (CMAC: must be full 32H, not truncated) verification_attributes: MAC algorithm parameters (mirrors generate_mac) mac_length: MAC length in nibbles/hex-digits (NOT bytes): 8=4-byte MAC, 16=8-byte MAC; must match the value used during generation

Call this before implementing any EMV PIN change flow — issuer script, CHANGE REFERENCE DATA (INS=24), or offline PIN change MAC assembly.

IMPORTANT: This operation requires THREE separate keys, not one: P0 — PIN Encryption Key: encrypts the new PIN block E2 — EMV Integrity Key: generates the script MAC E1 — EMV Confidentiality Key: encrypts the script data

Single-key EMV MAC helpers (E2 only) cannot replicate this. A full EMV PIN change requires all three key types to be provisioned in APC separately.

Required key types: new_pin_pek_identifier: P0 (PIN Encryption Key for new PIN) secure_messaging_integrity_key_identifier: E2 (EMV integrity) secure_messaging_confidentiality_key_identifier: E1 (EMV confidentiality)

Args: new_pin_pek_identifier: ARN or alias of P0 key for new PIN secure_messaging_integrity_key_identifier: ARN or alias of E2 key secure_messaging_confidentiality_key_identifier: ARN or alias of E1 key message_data: Hex-encoded script command data new_encrypted_pin_block: Hex-encoded new PIN block encrypted under PEK pin_block_format: ISO_FORMAT_0, ISO_FORMAT_1, or ISO_FORMAT_3 (ISO_FORMAT_4 is not supported by this operation) derivation_method_attributes: EMV derivation method (Visa, Mastercard, etc.)

Call this to mint a test/reference ARQC — e.g. to exercise an ARQC verification path, drive a proxy differential test, or produce the APC leg of a cross-implementation check. Issuers normally VERIFY ARQCs (the chip generates them), so this operation is primarily a test-vector generator. The inverse of verify_auth_request_cryptogram (POST /cryptogram/generate).

Required key type: E0 (EMV Application Cryptogram Master Key), TDES only, created/imported with DeriveKey mode. Every AES E0 key is rejected — asymmetric with verify_auth_request_cryptogram, which requires AES-256 E0 for AES ARQCs — so APC cannot mint an AES ARQC. NoRestrictions E0 keys are also rejected by this operation specifically.

transaction_data must be pre-padded with ISO 9797-1 method-2 (EMV) padding: append 0x80 then 0x00 to the next 8-byte boundary. APC does not pad, exactly as on the verify side.

session_key_derivation_attributes — exactly one member; PAN and PSN live inside it. Amex and Visa take only PAN+PSN (no ATC/UN — do not forward payShield ATC/UN wire fields for these schemes): {"Visa": {"PrimaryAccountNumber": "...", "PanSequenceNumber": "01"}} {"Amex": {"PrimaryAccountNumber": "...", "PanSequenceNumber": "01"}} {"Emv2000": {..., "ApplicationTransactionCounter": "0001"}} {"EmvCommon": {..., "ApplicationTransactionCounter": "0001"}} {"Mastercard": {..., "ApplicationTransactionCounter": "0001", "UnpredictableNumber": "12345678"}} {"UnionPay": {..., "ApplicationTransactionCounter": "0001"}}

UnionPay (CUP / PBOC) takes PAN + PSN + ATC and no UnpredictableNumber. It was added to APC on 2026-07-15 and needs boto3 >= 1.43.49 — on older boto3 the member is not in the service model and the call fails client-side with ParamValidationError.

Args: key_identifier: ARN or alias of TDES E0 key (DeriveKey mode) transaction_data: Hex-encoded EMV transaction data, method-2 pre-padded major_key_derivation_mode: EMV_OPTION_A (PAN <= 16 digits) or EMV_OPTION_B (PAN > 16 digits) session_key_derivation_attributes: single-member union, see above

Call this when implementing EMV transaction authorization (ARQC verification), generating an issuer ARPC response, or validating EMV session key derivation. ISO 8583 field 55 carries the ARQC and ATC from the chip card.

Verifies an EMV Authorization Request Cryptogram (ARQC) and optionally generates an Authorization Response Cryptogram (ARPC) in the same call.

Required key type: E0 (EMV Application Cryptogram Master Key). APC requires AES-256 E0 keys — AES-128 E0 keys are rejected at the API level.

major_key_derivation_mode options: EMV_OPTION_A — Visa/Amex ARQC derivation EMV_OPTION_B — Mastercard ARQC derivation

session_key_derivation_attributes — exactly one member, same union as generate_auth_request_cryptogram (Visa, Amex, Emv2000, EmvCommon, Mastercard, UnionPay): {"EmvCommon": {"ApplicationTransactionCounter": "0001", "PanSequenceNumber": "01", "ApplicationCryptogram": ""}} {"UnionPay": {"PrimaryAccountNumber": "...", "PanSequenceNumber": "01", "ApplicationTransactionCounter": "0001"}}

UnionPay (CUP / PBOC) was added to APC on 2026-07-15 and needs boto3 >= 1.43.49 — on older boto3 the call fails client-side with ParamValidationError. This is the APC target for the payShield JS command and for KW Scheme ID 'C'.

auth_response_attributes (to generate ARPC in same call): {"ArpcMethod1": {"AuthResponseCode": "0010"}} or {"ArpcMethod2": {"CardStatusUpdate": "00000000", "ProprietaryAuthenticationData": ""}}

ISO 8583 field 55 contains the EMV data including ARQC and ATC (tag 0x9F36).

Args: key_identifier: ARN or alias of E0 key transaction_data: Hex-encoded EMV transaction data for ARQC verification auth_request_cryptogram: Hex-encoded ARQC from the chip card major_key_derivation_mode: EMV_OPTION_A or EMV_OPTION_B session_key_derivation_attributes: ATC and session key derivation params auth_response_attributes: Optional ARPC generation parameters

Call this when implementing ECDH-based key agreement — for example, deriving a shared session key from an ECC key pair and a counterparty certificate, then wrapping the result as a TR-31 key block for local use. Also use when a key exchange protocol delivers a key via Diffie-Hellman and you need it in APC format.

Translate an ECDH-wrapped TR-31 key block into a KEK-wrapped TR-31 key block without ever importing the working key into APC storage.

The only documented use case is ECDH → TR-31 (KEK): incoming_key_material = { "DiffieHellmanTr31KeyBlock": { "CertificateAuthorityPublicKeyIdentifier": "", "KeyBlockHeaders": {...}, "PrivateKeyIdentifier": "", "PublicKeyCertificate": "", "DerivationData": "", "KeyAlgorithm": "AES_128", "KeyDerivationFunction": "NIST_SP800", "KeyDerivationHashAlgorithm": "SHA_256" } } outgoing_key_material = { "Tr31KeyBlock": { "WrappingKeyIdentifier": "" } }

key_check_value_algorithm: CMAC, ANSI_X9_24, HMAC, or SHA_1

Args: incoming_key_material: ECDH-wrapped TR-31 key block (DiffieHellmanTr31KeyBlock) outgoing_key_material: Target KEK-wrapped TR-31 output (Tr31KeyBlock) key_check_value_algorithm: Optional KCV algorithm for the output key block

Call this when implementing Australian AS2805 payment network key exchange — generating the KEK validation request or response value for node-to-node symmetric key establishment between an acquirer switch and a card scheme.

Generate an AS2805 Key Encryption Key validation value. Used in Australian payment network node-to-node key exchange.

kek_validation_type: KekValidationRequest — initiating node generates a validation request KekValidationResponse — responding node generates the validation response

random_key_send_variant_mask: VARIANT_MASK_82C0 — standard AS2805 variant mask VARIANT_MASK_82 — alternate AS2805 variant mask

Args: key_identifier: ARN or alias of the AS2805 KEK kek_validation_type: KekValidationRequest or KekValidationResponse random_key_send_variant_mask: VARIANT_MASK_82C0 or VARIANT_MASK_82

Call this before designing any transaction logging, audit trail, or database schema that processes ISO 8583 transactions containing field 52 (PIN block). Works without AWS credentials.

Returns the PCI PIN Req 4 rule: encrypted PIN blocks must not be retained in logs after the authorization response is received — even encrypted form is prohibited.

Call this before implementing any PIN translation flow where the PAN might differ between the inbound and outbound formats, or when asked about PCI PIN Req 3-3 / ISO 9564 PAN handling. Works without AWS credentials.

Returns the PCI PIN rule: the PAN must not change during any PIN block translation.

Call this whenever you see an HSM command code in legacy payment code, documentation, or logs — e.g. "TPIN", "CA", "G0", "M6", "CC", "CI", "CW", "CY", "B2", "KQ", "GW", or numeric Atalla codes like "31", "5D". Works without AWS credentials.

Returns the command name, category (PIN/MAC/CVV/KEY_MGMT/ENCRYPT/ARQC), description, and the APC operation + key type that replaces it.

Coverage: Futurex Excrypt (authoritative), Thales payShield legacy + international (authoritative/reference quality), Atalla numeric codes (directory quality).

Args: command_code: The HSM command code, e.g. "TPIN", "CA", "31" api: Optional API filter — "Excrypt", "Standard", or "International"

Call this for a quick command-code → APC operation lookup when you already know the command and just need the migration target — faster than hsm_lookup_command when you don't need the full description and notes. Works without AWS credentials.

Returns just the APC operation and key type for an HSM command.

Args: command_code: The HSM command code, e.g. "TPIN", "CA", "31"

Call this to discover which HSM commands are known and what APC operations they map to — useful when scoping a migration, reviewing an HSM integration, or deciding which APC operations a proxy handler needs to implement. Works without AWS credentials.

Args: category: PIN, MAC, CVV, KEY_MGMT, ENCRYPT, ARQC, or P2PE — omit for all vendor: "Futurex" or "Thales" — omit for all vendors

Call this whenever reviewing legacy payment code that may contain HSM socket calls — Python, Java, C, Go, or any language. Even a single file or function is worth scanning. Works without AWS credentials.

Detects Futurex Excrypt commands ([AOCCCC;...] frames), Thales/International 2-char command codes, and Atalla/Futurex Standard numeric codes. Returns identified commands, their APC migration path, and migration notes for LMK, DUKPT, and fixed-key patterns.

Args: source_code: Raw source code containing HSM socket calls or command strings.

Call this when analyzing the output of apc-hsm-proxy running in discovery mode (a discovery.jsonl file). Returns per-command APC mappings, which proxy handlers already exist, which still need to be written, and migration notes. Works without AWS credentials.

IMPORTANT — handler_exists reflects _PROXY_HANDLERS in hsm_tools.py, not the apc-hsm-proxy source tree. When a handler is completed in the proxy, update _PROXY_HANDLERS in this file so handler_exists reports correctly. Until that update is committed and the MCP server restarted, handler_exists will show false even for commands that already have working handlers.

Each log line is a JSON object: vendor — "futurex_excrypt" or "thales_payshield" cmd — HSM command code, e.g. "TPIN" or "CA" params — Futurex: parameter codes → values (sensitive fields = "[REDACTED]") payload_len — Thales: observed payload length in bytes

Args: log_content: Full text of the discovery.jsonl file (newline-delimited JSON).

Call this when discussing HSM migration for concepts that have no direct APC equivalent — LMK (Local Master Key), DUKPT initial key loading, or fixed ZPK key schemes. Returns detailed migration guidance for the selected topic. Works without AWS credentials.

Args: topic: One of "lmk", "dukpt", "fixed_key"

Call this whenever you discover a gap while working in any repo — apc-hsm-proxy, CyberChef-Payments, or any other session — and the finding belongs in this MCP server's knowledge base, HSM command registry, proxy handler list, or compliance rules. Works without AWS credentials.

Stages the finding as a GitHub issue so the MCP server session can apply it at the next session start. Returns a formatted issue body and the exact gh CLI command to run.

finding_type options: "kb_entry" — new or corrected entry for payment-knowledge-base.md "hsm_command" — new HSM command to add to hsm_analysis.py ALL_COMMANDS "proxy_handler" — handler completed in apc-hsm-proxy; needs _PROXY_HANDLERS update "compliance_rule" — new PCI or scheme rule for compliance.py "apc_constraint" — APC API gap or undocumented constraint for AGENTS.md

Args: finding_type: One of the five types above summary: One-line description — becomes the GitHub issue title content: The content to add, formatted for the target file (KB YAML, HsmCommand(), etc.) source_repo: Which repo or context revealed this — e.g. "apc-hsm-proxy GW handler" context: Optional additional context — related files, downstream impact, etc.