Skip to main content

Payment Card Industry Data Security Standard compliance

Guidelines for using Vault for Payment Card Industry Data Security Standard (PCI DSS) compliance​

Learn about deploying Vault, property data types, encryption, key storage, masking, tokenization, IAM and data access policies, and audit log configuration to achieve and remain PCI compliant with Piiano Vault.

Deploying Vault​

Hosted deployment​

In the hosted (SaaS) deployment, Piiano handles the deployment and configuration of your vault. The production hosted environment is PCI-compliant. Several steps described in the self-hosted deployment are handled by Piiano for the hosted deployment. Contact us to get a hosted PCI Vault instance or start with our self-service sandbox environment.

Piiano must validate that your payment gateways are PCI-compliant for regulatory reasons. Therefore, you can only send credit card information to payment gateways after Piiano approves and configures them in your vault.

⚠️ While the production environment is PCI compliant, the sandbox environment is not. It is only intended for testing purposes. Real primary account numbers are NOT allowed. Instead, use test data and test credit card numbers such as 4111-1111-1111-1111.

Self-hosted deployment​

In addition to using a recommended deployment method, such as Terraform, it is important to follow these best practices:

  • Deploy Vault and its backend database, for example, RDS, in a dedicated virtual private cloud (VPC).
  • Vault's VPC should not be internet-facing. However, if it has to be, use an allowlist to ensure only trusted addresses can access it.
  • Follow best practices in securing your cloud account, specifically:
    • Each user should have an IAM account. Don't share IAM accounts between users.
    • Require multi-factor authentication (MFA) for all users.
  • Create an encryption key and securely store it using a cloud provider's KMS service. For example, AWS KMS.
  • Use appropriate logging and audit logging mechanisms for your system, including Vault.
  • Separate your production environment from your testing or staging environments. The deployments should be in different accounts or, at least, different VPCs.
  • Never load production data into a Vault used for testing. Instead, use test data for testing.
  • Run the quick validation for a working Vault CLI command to ensure Vault is set up and working correctly.

Vault is production-ready. However, for PCI DSS compliance, follow these guidelines:

  • Ensure no test collections or data are present in your production Vault.
  • Switch dev-mode off.
  • Set the admin's API key to a non-default value.
  • Monitor your Vault instance's logs and audit logs.
  • Configure TLS for encryption of data in transit.
  • Add these PCI specific settings:
    • Configure PVAULT_SERVICE_PCI_RESTRICTIONS to true.
    • Add your payment gateway domains to the PVAULT_SERVICE_ALLOWED_PCI_HTTP_DESTINATIONS environment variable.
    • Configure PVAULT_SERVICE_ALLOW_ORIGINS for CORS support.

Property data types​

Vault includes property data types that help you comply with PCI DSS requirements. These types include:

  • BAN – bank account number
  • CC_NUMBER – credit card number
  • CC_EXPIRATION_STRING – credit card expiration month and year in the format MM/YYYY
  • CC_HOLDER_NAME – credit card holder name
  • CC_CVV – credit card verification value
  • US_BANK_ROUTING – US bank routing code
  • US_BANK_ACCOUNT_NUMBER – US bank account number

These property data types include built-in features, such as masking, that save you time and are required to meet your PCI DSS compliance requirements.

See the Data types reference for more details.

To remain PCI compliant, you must adhere to these requirements:

  1. Store credit cards numbers using the CC_NUMBER data type.

  2. Store CVV using the CC_CVV data type.

  3. Delete the CVV after completing the payment transaction that used it. Requirement 3 of the PCI specification stipulates the deletion of sensitive authentication data types. The only relevant type for Vault is the CVV.

    It is your responsibility to remove CVVs as soon as possible. However, Piiano includes some fail-safe measures:

    • In the hosted deployment, objects containing CVV data automatically expire within one hour. If the fail-safe deletes more than 10% of your CVVs, Piiano triggers an alert indicating that you are not complying with the self-deletion requirement.
    • In a self-hosted deployment, you can set the expiration for objects containing a CVV to one hour using the Vault configuration PVAULT_SERVICE_PCI_RESTRICTIONS environment variable. You must also set up an alert to warn you if your CVV data is being deleted using this method. You set this alert by querying the logs and searching for "Warning: objects with CVV have not expired in one hour".

    You can extend the expiration objects containing CVV by up to an hour for delayed transactions by modifying the object's built-in _expiration_time property.

Encryption​

Vault encrypts all properties by default. It is possible to define some properties as unencrypted. However, the PCI DSS requires that PANs be encrypted at rest and in transit. Therefore, encrypt all properties holding sensitive financial data using Vault's encryption mechanism.

note

The hosted deployment enforces all properties to be encrypted.
You can not create a non-encrypted property on the hosted deployment.

Key storage​

Vault supports local key storage. However, in a production deployment, it is recommended that you configure Vault to use a cloud provider's KMS service. For example, AWS KMS or GCP Cloud Key Management.

Both AWS KMS and GCP can be configured to use a Hardware Security Module (HSM) to increase your key security and to comply with PCI HSM. Further reading: AWS support for HSM, GCP support for HSM.

note

The hosted deployment enforces the use of AWS KMS.

Masking​

PCI DSS requirements mandate that the full primary account number (PAN) should never be rendered on client machines. Using a mask, this requirement can be easily met. For example, assume a PAN is held in the property cc_number, you can limit access by granting your application read permissions to cc_number.mask only. Then, your application gets a PAN where only the last 4 digits of the number are readable.

An advantage of using Vault's data types is that they support masks and transformations. For instance, you can use BAN.mask or CC_NUMBER.mask to receive a bank account or credit card number with all the digits masked except for the last 4. For example, ************2795.

Accessing​

Vault enforces the PCI restrictions when the environment variable PVAULT_SERVICE_PCI_RESTRICTIONS is set to true:

  • a deny policy for reading and detokenizing PAN is injected into all policies in the IAM.
  • tokenizing PAN is not allowed for tokens of type deterministic.
  • custom transformations are not allowed for PAN.
  • custom data types based on PAN are not allowed.
note

The hosted deployment enforces that the full PAN is never returned to the API caller in clear text.

Tokenization​

The PCI DSS requires that PANs are rendered unreadable in all places where they are stored. Vault tokenization provides for this requirement. Using Vault, you can create a token that represents sensitive PII data, use that token in calculations, and safely store it outside Vault.

Also, token are useful for some financial data use cases where masked values are not sufficient. For example, if you want to count the number of transactions that used a specific credit card, referring to the masked card number does not work. However, this use case can be addressed with a token that shares a common ID for the tokenized values.

Note that Vault tokens can refer to particular data items, not just records. For example, a token can refer to a bank account number several people share. The record for each person using this bank account can therefore contain the same token.

Vault provides two types of token specifically to address PCI requirements:

  • pci – tokens that represent property values as they were when the token was created. The token ID reuses the ID of an existing token where both tokens are created on the same collection with the same values and scope. Otherwise, the token ID is randomly assigned.
  • pci_oneway – PCI tokens that cannot be detokenized.

See Tokenize personal data to learn how to tokenize your data.

As with other entities in Vault, users can be granted access to tokenized data only or specific tokens.

Where you need to store PII data in an application's database or refer to PII data outside Vault, it is highly recommended that you use only tokenized data.

note

The PCI standard for tokenization requires that "...tokens should be distinguishable from a valid PAN...". If you still intend on using format preserving tokens for PAN, you should seek legal advice pertaining your specific use case.

IAM and data access policies​

The PCI DSS includes several requirements for data access policies, all of which are supported by Vault.

These recommendations can help you configure Vault to comply with these requirements. See Manage users and policies to learn how to implement them.

  • Create separate users for each of your applications, so each has a different API key.
  • Each application's user account should have its own role, with access limited to the collections it uses.
  • Applications should not have read access to sensitive data. Instead, provide access to only tokenized or masked versions. Specifically, only grant read access to masked or tokenized PANs (credit card numbers).
  • Every person with access to Vault should have a user account and API key. User accounts and API keys should not be shared between different people. However, users can have similar roles. Roles should be used to limit access to the minimal set of entities the user needs for their business use case. Note that Vault policies and positions are deny-all by default; as such, you only need to add allow access to the entities required by the user.
  • Technical administrators should not have access to PII data. They should only be able to access the control operations in the REST API and CLI.
  • Revoke peoples' access immediately upon departure or termination by removing their user from the IAM configuration.

Audit log configuration​

Vault supports creating and tracking an audit log. The PCI DSS requires that you keep an audit log of actions made on cardholder data. Vault's audit log will NEVER include sensitive PII data, so depending on Vault's audit log capabilities ensures that no PAN data appears in your audit logs.

Vault's audit log entries always include:

  • The user account that took the action
  • The type of the action or event
  • Timestamp
  • Success or failure
  • Reason for action, as provided in the CLI or API.

It is recommended that you store all audit logs generated by Vault appropriately. In addition to depending on Vault's logs, you should also log access to the audit logs and make sure they are unalterable and backed up. Note that you should retain the audit log for at least a year, with the most recent 3 months available for immediate search and review.

Further evidence​

To help you successfully complete a PCI Compliance audit, Piiano can provide paying customers with any additional evidence required and assistance in integrating Vault in a compliant manner. Please contact info@piiano.com for additional information.

Examples and tutorials​

Find out more about setting up PCI-compliant vaults:

On this page