AWS Payment Cryptography

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 VA…

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 …

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: {"DynamicCard…

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"} HM…

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…

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": {"DecimalizationTab…

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 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 …

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 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 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 …

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 pa…

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,…

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 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 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 alread…

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 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", "…

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 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 un…

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 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 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 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 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 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 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 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…

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 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 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 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": { "CertificateAuthorityPublicK…

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 fl…

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 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 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 …

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 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…

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): {"Ke…