# Region specific features for AWS Payment Cryptography
<a name="advanced.regional"></a>

Certain features may be region specific and not otherwise used. Those features are described in more detail in this section.

# AS2805
<a name="advanced.regional.as2805"></a>

Australia Standard 2805 (AS2805) is a standard for electronic funds transfers used primarily for card-based payment transactions. It is maintained by [Standards Australia](https://www.standards.org.au/). The standard consists of 6 books that covers numerous topics from message format to encryption standards.

Part 6 provides guidance on key management including host-to-host (node-to-node) communication and relevant cryptographic requirements while other aspects are covered in other parts. All cryptography in this standard is currently based on TDES. 

**Note**  
 AS2805 is currently available in the ap-southeast-2 Region. It will be rolled out to additional Regions in the near future. 

AS2805 has a number of differences compared to other implementations, which are summarized below.

*Key Protection*  
Relies on key variants instead of keyblocks such as in TR-31/X9.143. AWS Payment Cryptography stores all keys as key blocks internally but permits import, export and calculation using AS2805 defined variants. 

*Unidirectional Keys*  
AS2805 mandates the use of unidirectional keys. If both nodes need to generate message authentication codes (MAC), they use two keys. 

*Pin Blocks*  
AS2805 defines a key derivation technique for unique pin encryption keys per transaction. This can be used in lieu of DUKPT. The AS2805 scheme relies on transaction data (trace number and transaction amount) as compared to DUKPT's use of transaction counter. 

*Key Exchange Validation*  
Defines a process to validate KEK before beginning to exchange working keys such as pin keys. In other schemes, KEK are exchanged infrequently and are validated using KCV. 

AS2805 uses the concept of key variants rather than key blocks to ensure keys are only used for the intended (and sole) purpose. The following is how AWS Payment Cryptography maps between variants and keyblocks when importing, exporting or performing other cryptographic functions with keys.


| AS2805 Key Type | AWS Payment Cryptography Key Type | 
| --- | --- | 
| TERMINAL\$1MAJOR\$1KEY\$1VARIANT\$100 |  TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY | 
| PIN\$1ENCRYPTION\$1KEY\$1VARIANT\$128 |  TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY | 
| MESSAGE\$1AUTHENTICATION\$1KEY\$1VARIANT\$124 |  TR31\$1M0\$1ISO\$116609\$1MAC\$1KEY | 
| DATA\$1ENCRYPTION\$1KEY\$1VARIANT\$122 |  TR31\$1D0\$1SYMMETRIC\$1DATA\$1ENCRYPTION\$1KEY | 
| VARIANT\$1MASK\$182,VARIANT\$1MASK\$182C0 |  Options available as part of KEK validation process. These key types are ephemeral and are not stored by the service. | 

Given two nodes, node1 and node2, the following examples are from the perspective of node1. AWS Payment Cryptography supports APIs from both sides of the process.

**Topics**
+ [Initial Key(KEK) exchange](as2805.kekexchange.md)
+ [Validation of KEK](as2805.kekvalidation.md)
+ [Creation and transmission of working keys](as2805.workingkeys.create.md)
+ [Exporting working keys](as2805.workingkeys.export.md)
+ [Pin Translation](as2805.pintranslation.md)
+ [Mac Generation and Validation](as2805.mac.md)

# Initial Key(KEK) exchange
<a name="as2805.kekexchange"></a>

 In AS2805, each side has their own KEK. KEK(s) refers to the sending side key that will be used whenever the sending side needs to protect/wrap keys and send them to node2. KEK(r) is the key created by the opposite(node2) side.

**Note**  
These terms are relative - one side creates a key (sending side) and the other side receives it. So given KEY1, it is referred to on node1 as KEK(s) and on node2 as KEK(r).

 KEK for AS2805 are always key type = TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY as they are used to protect cryptograms and not key blocks. This maps to TERMINAL\$1MAJOR\$1KEY\$1VARIANT\$100 as defined in AS2805 6.1 

Steps:

**1.Create a key**  
Create a key using the [CreateKey](create-keys.md) api. You will create a key of type TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY

**2.Determine method to exchange keys with node2**  
Determine how to [exchange KEK with the counter party](keys-export.md). For AS2805, the most common and interoperable method is RSA Wrap.

**3.Export KEKs**  
Based on your selection above, you will receive public key certificate from node2. You will run export using that certificate to protect the key (or derive a key if using ECDH).

**4. Import KEKr**  
Based on your selection above, you will send a public key certificate to node2. You will run import using that certificate to to load node 2's KEKr into the service.

# Validation of KEK
<a name="as2805.kekvalidation"></a>

![\[Example high level network diagram for a PIN applications using AWS Payment Cryptography\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/images/as2805/kek_validation.png)


When your service (node1) connects to node2, each side will ensure that they are using the same KEK for subsequent operations using a process called KEK Validation. 

**1. Steps to validate the first key**

**1.1 Receive KRs**  
Node2 will generate a KRs and send it to you as part of the logon process. They may use AWS Payment Cryptography to generate this value or another solution.

**1.2 Generate KEK Validation Response**  
Your node will generate a KEK Validation response with inputs as the KEK(r) and the KRs provided in step 1.  

**Example**  

```
cat >> generate-kek-validation-response.json
{
    "KekValidationType": {
        "KekValidationResponse": {
            "RandomKeySend": "9217DC67B8763BABCFDF3DADFCD0F84A"
        }
    },
    "RandomKeySendVariantMask": "VARIANT_MASK_82",
    "KeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza"
}
```

```
$ aws payment-cryptography-data generate-as2805-kek-validation --cli-input-json file://generate-kek-validation-response.json
```

```
{
 "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza",
 "KeyCheckValue": "0A3674",
 "RandomKeyReceive": "A4B7E249C40C98178C1B856DB7FB76EB",
 "RandomKeySend": "9217DC67B8763BABCFDF3DADFCD0F84A"
}
```

**1.3 Return calculated KRr**  
Return the calculated KRr to node2. That node will compare it against the calculated value from step 1.

**2.Steps to validate the second key**

**2.1 Generate KRr and KRs**  
Your node will generate a random value and an inverted(reversed) copy of this value using AWS Payment Cryptography. The service will output both of these values wrapped by the KEK(s). These are known as KR(s) and KR(r).  

**Example**  

```
cat >> generate-kek-validation-request.json 
{
    "KekValidationType": {
        "KekValidationRequest": {
            "DeriveKeyAlgorithm": "TDES_2KEY"
        }
    },
"RandomKeySendVariantMask": "VARIANT_MASK_82",
    "KeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/rhfm6tenpxapkmrv"
}
```

```
$ aws payment-cryptography-data generate-as2805-kek-validation --cli-input-json file://generate-kek-validation-request.json
```

```
{
 "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/rhfm6tenpxapkmrv",
 "KeyCheckValue": "DC1081",
 "RandomKeyReceive": "A4B7E249C40C98178C1B856DB7FB76EB",
 "RandomKeySend": "9217DC67B8763BABCFDF3DADFCD0F84A"
}
```

**2.2 Send KRs to node2**  
Send the KRs to node2. Keep the KRr for later validation.

**2.3 Node2 generates KEK validation response**  
Node2 uses the KEKr and KRs, generates the KRr and sends it back to your service.

**2.4 Validate response**  
Compare KRr from step 1 and the value returned from step 3. If they match, proceed.

# Creation and transmission of working keys
<a name="as2805.workingkeys.create"></a>

Typical working keys used in AS2805 includes two sets of keys:

Keys between nodes such as: zone pin key(ZPK), zone encryption key (ZEK) and zone authentication key(ZAK).

Keys between terminals and nodes such as: terminal main key(TMK) and terminal pin key(TPK) if not using DUKPT.

**Note**  
We recommend minimizing key per terminal keys and leveraging techniques such as TR-34 and DUKPT whenever possible that use smaller numbers of keys.

**Example**  
In this example, we've used optional tags to track the purpose and use of this key. Tags are not used as part of the cryptographic function of the system but can be used for categorization, financial tracking and can be used to apply IAM policies.  

```
cat >> create-zone-pin-key.json 
{
    "KeyAttributes": {
        "KeyUsage": "TR31_P0_PIN_ENCRYPTION_KEY",
        "KeyClass": "SYMMETRIC_KEY",
        "KeyAlgorithm": "TDES_2KEY",
        "KeyModesOfUse": {
            "Encrypt": true,
            "Decrypt": true,
            "Wrap": true,
            "Unwrap": true,
            "Generate": false,
            "Sign": false,
            "Verify": false,
            "DeriveKey": false,
            "NoRestrictions": false
        }
    },
    "KeyCheckValueAlgorithm": "ANSI_X9_24",
    "Exportable": true,
    "Enabled": true,
    "Tags": [
        {
            "Key": "AS2805_KEYTYPE",
            "Value": "ZONE_PIN_KEY_VARIANT28"
        }
    ]
}
```

```
$ aws payment-cryptography-data create-key --cli-input-json file://create-zone-pin-key.json --region ap-southeast-2
```

```
{
 "Key": {
 "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh",
 "KeyAttributes": {
 "KeyUsage": "TR31_P0_PIN_ENCRYPTION_KEY",
 "KeyClass": "SYMMETRIC_KEY",
 "KeyAlgorithm": "TDES_2KEY",
 "KeyModesOfUse": {
 "Encrypt": true,
 "Decrypt": true,
 "Wrap": true,
 "Unwrap": true,
 "Generate": false,
 "Sign": false,
 "Verify": false,
 "DeriveKey": false,
 "NoRestrictions": false
 }
 },
 "KeyCheckValue": "9A325B",
 "KeyCheckValueAlgorithm": "ANSI_X9_24",
 "Enabled": true,
 "Exportable": true,
 "KeyState": "CREATE_COMPLETE",
 "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
 "CreateTimestamp": "2025-12-17T09:05:27.586000-08:00",
 "UsageStartTimestamp": "2025-12-17T09:05:27.570000-08:00"
 }
}
```

# Exporting working keys
<a name="as2805.workingkeys.export"></a>

To maintain compatibility with other parties, AWS Payment Cryptography supports AS2805 symmetric key wrapping techniques which use key variants instead of keyblocks like TR-31. If multiple keys are shared between parties, each should be exported individually. If data is sent bi-directionally, there may be two keys between parties of the same type such as ZAK(s) and ZAK(r) that are used by each side to generate message authentication codes. 

The additional parameters to import and export in these formats are specified on the commands.

```
cat >> export-zone-pin-key.json 
{
    "ExportKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh",
    "KeyMaterial": {
        "As2805KeyCryptogram": {
            "WrappingKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/rhfm6tenpxapkmrv",
            "As2805KeyVariant: "PIN_ENCRYPTION_KEY_VARIANT_28"
        }
    }
}
```

```
$ aws payment-cryptography-data export-key --cli-input-json file://export-zone-pin-key.json --region ap-southeast-2
```

```
{
    "WrappedKey": {
        "KeyCheckValue": "DC1081",
        "KeyCheckValueAlgorithm": "ANSI_X9_24",
        "KeyMaterial": "HDC10AEF038E695DDD72AF08DC1BB422D",
        "WrappedKeyMaterialFormat": "KEY_CRYPTOGRAM",
        "WrappingKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/rhfm6tenpxapkmrv"
    }
}
```

# Pin Translation
<a name="as2805.pintranslation"></a>

AS2805 describes a session specific key derivation mode in section 6.4. It serves a similiar purpose as DUKPT and either algorithm can be used as DUKPT is covered in section 6.7. In this scheme, a session pin key (known as a KPE) is derived from the Terminal Pin Key using SystemTraceAuditNumber(STAN) and TransactionAmount as the derivation data.

Translate pin is a common function that can translate to/from a variety of formats. In this example, we translate a pin from a KPE to a pin encryption key (PEK) such as when sending a pin to a payment network.

```
cat >> translate-pin-as2805.json 
{
    "EncryptedPinBlock": "B3B34B43BAB5F81A",
    "IncomingKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt",
    "IncomingTranslationAttributes": {
        "IsoFormat0": {
            "PrimaryAccountNumber": "9999179999900013"
        }
    },
      "IncomingAs2805Attributes": {
        "SystemTraceAuditNumber": "000348",
        "TransactionAmount": "000000000328"
    },
    "OutgoingKeyIdentifier": "",
    "OutgoingTranslationAttributes": {    
        "IsoFormat0": {
            "PrimaryAccountNumber": "9999179999900013"
        }
    }
}
```

```
$ aws payment-cryptography-data translate-pin-data --cli-input-json file://translate-pin-as2805.json  --region ap-southeast-2
```

```
{
    "WrappedKey": {
        "KeyCheckValue": "DC1081",
        "KeyCheckValueAlgorithm": "ANSI_X9_24",
        "KeyMaterial": "HDC10AEF038E695DDD72AF08DC1BB422D",
        "WrappedKeyMaterialFormat": "KEY_CRYPTOGRAM",
        "WrappingKeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/rhfm6tenpxapkmrv"
    }
}
```

# Mac Generation and Validation
<a name="as2805.mac"></a>

The generate and verify MAC commands support a variety of MACs including HMAC, CMAC, EMV MAC, etc. For AS2805, there is an additional variation defined in AS2805.4.1. Typically in AS2805, incoming messages are verified using this MAC and outgoing messages include a MAC as well. 

```
cat verify-mac.json 
{
    "KeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6",
    "Mac": "86304058",
    "MessageData": "73D8BA54D3852951DAEA41",
    "VerificationAttributes": {
        "Algorithm": "AS2805_4_1"
    }
}
```

```
$ aws payment-cryptography-data verify-mac --cli-input-json file://verify-mac.json --region ap-southeast-2
```

```
{
    "KeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6",
    "KeyCheckValue": "2976E7"
}
```