# WhiteList Configuration (/global/en/docs/Terminal/P2PE-Security-Empowerment-SDK/P2PE-Application-PaymentLink/WhiteList-Configuration)

---

The PaymentLink whitelist file can be used to configure encryption key settings and define specific encryption policies for designated card number ranges during transactions. By loading the whitelist, organizations can achieve centralized and consistent management of encryption policies.

## Configuration Components

The PaymentLink whitelist data mainly consists of the following three components:

- **Encryption Key Configuration**

  Defines the encryption key configurations that may be used within the application, including key IDs, encryption methods, and algorithm parameters.

- **Card Number Range Configuration**

  Specifies custom encryption settings for specific card number ranges (e.g., BIN ranges), enabling granular security control.

- **Payment AID Supplement Configuration**

  Allows the addition of new Application Identifiers (AIDs) to be included in transaction management, supporting newly introduced payment applications or protocols.

![](https://docs.newlandnpt.us/assets/_shared/5756288c1463/whitelist_overview.png)

## Logical Parameters Classification

**Encryption Key Configuration, Card Number Range Configuration** and **Payment AID Supplement Configuration**, the relationship of the three main categories is shown in the diagram below.

> The **Card Number Range Configuration** table will be associated with the **Encryption Key Configuration** table to specify corresponding encryption policies for specific PAN ranges.
>
> Meanwhile, the **Payment AID Supplement Configuration** table exists independently and is used to manage newly added or specially controlled Application Identifiers (AIDs).
>
> Both the **Card Number Range Configuration** table and the **Payment AID Supplement Configuration** table are optional. They only need to be configured when required by business scenarios. The system can operate normally without these configurations if no special requirements exist.

![](https://docs.newlandnpt.us/assets/_shared/9f74c414faaa/whitelist_data_classification.png)

## Standard Usage Process

![](https://docs.newlandnpt.us/assets/_shared/103e86461ef8/whitelist_usage_flow.png)

## Encryption - Encryption Key Configuration

### Tag Description

| Tag              | Description                                                                                                                      | Option Value                                     | Presence |   |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -------- | - |
| EncryptID        | Encryption method ID, serves as a unique identifier                                                                              |                                                  | M        |   |
| KeySystem        | Encryption system used                                                                                                           | MK/SK DUKPT                                      | M        |   |
| KeyIndex         | Key ID in the key table                                                                                                          |                                                  | M        |   |
| Algorithms       | Encryption algorithms used                                                                                                       | DES AES                                          | M        |   |
| BlockMode        | Block cipher mode used during encryption                                                                                         | ECB CBC ECB\_RESP ECB\_BOTH CBC\_RESP CBC\_BOTH  | M        |   |
| IV               | Initialization vector, required when using CBC encryption mode                                                                   |                                                  | O        |   |
| Padding          | Padding mode, mainly used in CBC mode. Default is NONE                                                                           | NONE PKCS7 ONE\_AND\_ZEROS ZEROS\_AND\_LEN ZEROS | O        |   |
| DerivateType     | AES DUKPT derived key type                                                                                                       | DES AES                                          | O        |   |
| DerivateKeyLen   | AES DUKPT derived key length                                                                                                     |                                                  | O        |   |
| DerivateKeyUsage | AES DUKPT derived key usage                                                                                                      | DATA\_ENC DATA\_BOTH                             | O        |   |
| IsDefault        | Whether this is the default key. Defaults to false if not configured. Only one default configuration allowed in the entire setup | true false                                       | O        |   |
| FirstClearPAN    | Length of the first few digits of the PAN shown in plain text after masking                                                      |                                                  | O        |   |
| LastClearPAN     | Length of the last few digits of the PAN shown in plain text after masking                                                       |                                                  | O        |   |

### Example

**MK/SK - DES**

```xml
<entry name="Encryption">
    <item key="EncryptID" value="1">
    <item key="KeySystem" value="MK/SK">
    <item key="KeyIndex" value="1">
    <item key="Algorithms" value="DES">
    <item key="BlockMode" value="ECB">
    <item key="Padding" value="ZEROS"> 
    <item key="IsDefault" value="true">
</entry>
```

**MK/SK - AES**

```xml
<entry name="Encryption">
    <item key="EncryptID" value="2">
    <item key="KeySystem" value="MK/SK">
    <item key="KeyIndex" value="1">
    <item key="Algorithms" value="AES">
    <item key="BlockMode" value="CBC">
    <item key="Padding" value="ZEROS"> 
    <item key="IV" value="000000000000"> 
    
    <item key="IsDefault" value="false">
</entry>
```

##### DUKPT

**DUKPT - DES**

```xml
<entry name="Encryption">
    <item key="EncryptID" value="3">
    <item key="KeySystem" value="DUKPT">
    <item key="KeyIndex" value="1">
    <item key="Algorithms" value="DES">
    <item key="BlockMode" value="ECB">
    <item key="Padding" value="ZEROS"> 
</entry>
```

**DUKPT - AES**

```xml
<entry name="Encryption">
    <item key="EncryptID" value="3">
    <item key="KeySystem" value="DUKPT">
    <item key="KeyIndex" value="1">
    <item key="Algorithms" value="DES">
    <item key="BlockMode" value="CBC">
    <item key="Padding" value="ZEROS"> 
    <item key="IV" value="000000000000"> 
    
    <item key="DerivateType" value="AES">
    <item key="DerivateKeyLen" value="16">
</entry>
```

## Card Range - Card Number Range Configuration

### Tag Description

| Tag           | Description                                                                                       | Option Value                                                                                                | Presence |   |
| ------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | - |
| PanLen        | Length of the card number (PAN)                                                                   |                                                                                                             | M        |   |
| MinPan        | Minimum PAN value                                                                                 |                                                                                                             | M        |   |
| MaxPan        | Maximum PAN value                                                                                 |                                                                                                             | M        |   |
| EncryptID     | Specifies the corresponding encryption method ID, matching the identifier in the Encryption table | NO-Encrypted: For Pan Range which does not need to Encrypt. EncryptID in Encryption Key Configuration table | M        |   |
| KeyIndex      | Specifies the key ID to be used under the selected encryption method                              |                                                                                                             | O        |   |
| FirstClearPAN | Length of the first few digits of the PAN shown in plain text after masking                       |                                                                                                             | O        |   |
| LastClearPAN  | Length of the last few digits of the PAN shown in plain text after masking                        |                                                                                                             | O        |   |

### Example

```xml
<entry name="Card Range">
    <config name="A card">
        <item key="PanLen" value="15" />
        <item key="MinPan" value="370200000000000" />
        <item key="MaxPan" value="370299999999999" />
        <item key="EncryptID" value="NO-Encrypted" />
    </config>
    <config name="B card">
        <item key="PanLen" value="16" />
        <item key="MinPan" value="4518000000000000" />
        <item key="MaxPan" value="4518999999999999" />
        <item key="EncryptID" value="1" />
        <item key="KeyIndex" value="5" />
        <item key="FirstClearPAN" value="7" />
        <item key="LastClearPAN" value="4" />
    </config>
    <config name="C card">
        <item key="PanLen" value="16" />
        <item key="MinPan" value="6214000000000000" />
        <item key="MaxPan" value="6214999999999999" />
        <item key="EncryptID" value="3" />
        <item key="FirstClearPAN" value="6" />
        <item key="LastClearPAN" value="5" />
    </config>
    <config name="D card">
        <item key="PanLen" value="16" />
        <item key="MinPan" value="6250000000000000" />
        <item key="MaxPan" value="6250999999999999" />
        <item key="EncryptID" value="4" />
    </config>
</entry>
```

## Payment AID - Payment AID Supplement Configuration

### Tag Description

| Tag | Description                                   | Option Value | Presence |   |
| --- | --------------------------------------------- | ------------ | -------- | - |
| AID | Additional AID used for transaction filtering |              | M        |   |

### Example

```xml
<entry name="Payment AID">
    <item key="AID" value="A00000033301020304" />
</entry>
```

## Full WhiteList Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<whitelist>
    <entry name="Encryption">
        <item key="EncryptID" value="1" />
        <item key="KeySystem" value="MK/SK" />
        <item key="KeyIndex" value="3" />
        <item key="Algorithms" value="DES" />
        <item key="BlockMode" value="ECB" />
        <item key="Padding" value="NONE" />
        <item key="IsDefault" value="true" />
    </entry>

    <entry name="Encryption">
        <item key="EncryptID" value="2" />
        <item key="KeySystem" value="MK/SK" />
        <item key="KeyIndex" value="3" />
        <item key="Algorithms" value="AES" />
        <item key="BlockMode" value="CBC" />
        <item key="Padding" value="ZEROS" />
        <item key="IV" value="00000000000000000000000000000000" />
    </entry>

    <entry name="Encryption">
        <item key="EncryptID" value="3" />
        <item key="KeySystem" value="DUKPT" />
        <item key="KeyIndex" value="1" />
        <item key="Algorithms" value="DES" />
        <item key="BlockMode" value="ECB_BOTH" />
        <item key="Padding" value="NONE" />
        <item key="FirstClearPAN" value="6" />
        <item key="LastClearPAN" value="3" />
    </entry>

    <entry name="Encryption">
        <item key="EncryptID" value="4" />
        <item key="KeySystem" value="DUKPT" />
        <item key="KeyIndex" value="2" />
        <item key="Algorithms" value="AES" />
        <item key="BlockMode" value="CBC" />
        <item key="Padding" value="ZEROS" />
        <item key="IV" value="00000000000000000000000000000000" />
        <item key="DerivateType" value="AES" />
        <item key="DerivateKeyLen" value="16" />
        <item key="DerivateKeyUsage" value="DATA_BOTH" />
    </entry>

    <entry name="Card Range">
        <config name="A card">
            <item key="PanLen" value="15" />
            <item key="MinPan" value="370200000000000" />
            <item key="MaxPan" value="370299999999999" />
            <item key="EncryptID" value="NO-Encrypted" />
        </config>
        <config name="B card">
            <item key="PanLen" value="16" />
            <item key="MinPan" value="4518000000000000" />
            <item key="MaxPan" value="4518999999999999" />
            <item key="EncryptID" value="1" />
            <item key="KeyIndex" value="5" />
            <item key="FirstClearPAN" value="7" />
            <item key="LastClearPAN" value="4" />
        </config>
        <config name="C card">
            <item key="PanLen" value="16" />
            <item key="MinPan" value="6214000000000000" />
            <item key="MaxPan" value="6214999999999999" />
            <item key="EncryptID" value="3" />
            <item key="FirstClearPAN" value="6" />
            <item key="LastClearPAN" value="5" />
        </config>
        <config name="D card">
            <item key="PanLen" value="16" />
            <item key="MinPan" value="6250000000000000" />
            <item key="MaxPan" value="6250999999999999" />
            <item key="EncryptID" value="4" />
        </config>
    </entry>

    <entry name="Payment AID">
        <item key="AID" value="A00000033301020304" />
    </entry>
</whitelist>
```