The PSN is a simple concept. During new domain creation, you must choose the starting value of the PSN and the number of digits you want to use for your PSN. By default, SAKA is configured to use 16 digits as the PSN (to accommodate credit card numbers) and the starting value defaults to 1000000000000001 for server ID #1, 2000000000000001 for server ID #2 and so on. The New-Domain-Setup-Wizard.sh script that sets up new encryption domains in SAKA allows specification of the number of digits in the PSN and the starting number for each server of the cluster. Once specified, it is not a good idea to change it. It will be less complicated to create a new encryption domain with custom token numbers and write a small batch program to decrypt the old tokens; then re-encrypt them in the new encryption domain while updating your database with the new domain ID and token numbers.

By using PSNs, after the SAKA has completed encrypting the plaintext with the DEK and generated an HMAC with the DHK, it creates a new PSN for the object based on configured parameters, and returns the PSN to the calling application.

The advantage of using the PSN is that it never changes. The same PSN, regardless of the DEK or the DHK, will always result in the same plaintext as long as PSNs are used from the beginning when SAKA goes into production. Authorized applications that store the PSN as the token never need change the token value and can always call upon SAKA to return the original plaintext, regardless of how many key rotations have taken place between the initial encryption and decryption transactions.

This is because, when SAKA receives a new encryption request, even before it encrypts the data, it calculates the HMAC of the plaintext with the current DHK and checks to see if the internal database already has the HMAC stored in it. If it does exist, based on the value of tokentype, it returns either the HMAC or the PSN without doing any further processing. No duplicate record is created, but the fact that the request was found in the database is logged in the server's log file. Authorized applications do not see any difference in their request processing whether the value exists in the database or not—they always get back a token.

When the DEK and DHK change, the new ciphertext and HMAC values are calculated and stored in the internal database, but the PSN does not change. This allows applications to continue using the PSN to request decryption services from SAKA and get the same plaintext regardless of which DEK or DHK is in use at the current time.

NOTE: It is strongly recommended that sites always use the PSN even if they believe they will never store objects past the end of a calendar year. Business requirements may change, but by using the PSN from the start, applications will not have to change due to the new requirement.

The appliance also has the ability to issue tokens that conform to the Luhn algorithm¹. This allows tokens to be used within application that check for conformance to the Luhn algorithm. This can be enabled by configuring the strongkeylite.cfg.property.luhntokens property to be true; this can be done on at the level of the encryption domain, so one domain may be using Luhn-conformant tokens while others need not. It is necessary to restart the Payara application server before this property goes into effect. It is also recommended that this property be turned on immediately after creating the encryption domain to ensure that tokens are generated that conform to this specification.

NOTE: It is possible to store a significant number of unique PSNs for credit card numbers (hardware capacity permitting), given that startvalue for the PSN is 1000000000000001 by default; almost one quadrillion (1,000,000,000,000,000) unique credit card numbers can be stored. If this isn't enough, it is possible to create additional encryption domains and use startvalue all over again, thus creating almost infinite capacity. Since the Domain ID is a required piece of information in all SAKA web requests, SAKA knows from which encryption domain to retrieve the value. Of course, to avoid having to change database schemas if they choose to add additional encryption domains in the future, applications must store the unique Domain ID in their database with the token.