insert()
insert() API encrypts plaintext value(s), creates token(s), inserts token(s) into the token vault(s), and returns the token(s). The API supports Unicode (multibyte format) tokens.
If the passed plaintext value is already tokenized, this method simply returns the existing token. If the value is not already tokenized, but a collision occurs (the given token already exists) or the generated token matches the plaintext value, then CT-V repeats the tokenization process up to 100 times, to tokenized the plaintext value.
This method supports tokenization yielding Unicode (multi-byte character) tokens.
This method is overloaded to handle customData, value array, customData array, and saveExceptions.
Note
The parameter saveExceptions is the toggle for the “Smart Check” option, see Smart Check.
In the SafeNetToken.properties file, set the CheckTokenHash and NumTMThreads parameters value as ‘true’ and ‘1’, respectively. This is to check the duplicacy of the tokens generated against the input plain text values and the existing tokens in the token vault.
When CT-V encounters any duplicate value, it does the following:
If save exception is set true for the API, CT-V generates error message for that particular value and continue tokenization for other input plaintext values.
Otherwise, it stops further tokenization of the plaintext values and displays an error message.
Tip
The Smart Check option enables you to complete the process of bulk tokenization or detokenization of input data, even when row level errors (null values, invalid values) appear in the input.
Syntax
public String insert (String value, String table, int format, boolean luhnCheck) throws TokenException
public String insert (String value, String table, int format, boolean luhnCheck, TokenProperty tokenProperty) throws TokenException
public String insert (String value, String customData, String table, int format, boolean luhnCheck) throws TokenException
public String insert (String value, String customData, String table, int format, boolean luhnCheck, TokenProperty tokenProperty) throws TokenException
public String[] insert (String[] values, String table, int format, boolean luhnCheck) throws TokenException
public String[] insert (String[] values, String table, int format, boolean luhnCheck, TokenProperty tokenProperty) throws TokenException
public String[] insert(String[] values, String table, int format,boolean luhnCheck, TokenProperty[] tokenProperty) throws TokenException
public String[] insert (String[] values, String[] customData, String table, int format, boolean luhnCheck) throws TokenException
public String[] insert (String[] values, String[] customData, String table, int format, boolean luhnCheck, TokenProperty tokenProperty) throws TokenException
public String[] insert(String[] values, String[] customData, String table, int format, boolean luhnCheck, TokenProperty[] tokenProperty) throws TokenException
public TmResult insert (String[] values, String[] customData, String table, int format, boolean luhnCheck, boolean saveExceptions) throws TokenException
public String insert (String value, String customData, String table, ITokenGenerator tokenGenerator, TokenProperty tokenProperty) throws TokenException
public TmResult insert (String[] values, String[] customData, String table, ITokenGenerator tokenGenerator, boolean saveExceptions, TokenProperty tokenProperty) throws TokenException
public TmResult insert (String[] values, String[] customData, String table, int format, boolean luhnCheck, boolean saveExceptions, TokenProperty tokenProperty) throws TokenException
public TmResult insert(String[] values, String[] customData, String table, int format, boolean luhnCheck, boolean saveExceptions, TokenProperty[] tokenProperty) throws TokenException
public String insert (String value, String customData, String table, int format, boolean luhnCheck, ITokenValidator tokenValidator, TokenProperty tokenProperty) throws TokenException
public TmResult insert (String[] values, String[] customData, String table, int format, boolean luhnCheck, ITokenValidator tokenValidator, boolean saveExceptions, TokenProperty tokenProperty) throws TokenException
public String[][] insert(String[][] values, String[] table, int[] format, boolean luhnCheck, Tokenproperty[] tokenProperty) throws TokenException
Note
Multi-site is not supported for this Java API.
Request Parameters
| Parameters | Data types | Descriptions |
|---|---|---|
| value(s) | string[][] | The data to be tokenized. Input data can be no longer than 256 characters. Note: String[][] values are used with String[] table. Each array specifies the data to be tokenized using the corresponding token vault specified in array of table. |
| customData or customData[] | string or string[] | Customer-specific data to appear. |
| table or table[] | string or string[] | The token vault or token vaults. The table must be in CAPITAL LETTERS. |
| tokengenerator | The token generator. | |
| tokenvalidator | The token validator. | |
| format or format[] | integer or integer[] | One of the little below listed token formats or a format created using createNewFormat(). |
| luhnCheck | boolean | boolean indicates if the value must pass a Luhn check (true) or if there is no requirement (false). Token formats created using the createNewFormat() method may have one of three luhnCheck rules, the rules are must fail test, no requirement, and must pass test. |
| TokenProperty or TokenProperty[] | The tokenProperty/tokenProperty[] associated with the created tokens. | |
| boolean saveExceptions | boolean | Use this as a toggle to turn on the Smart Check feature. When set to true, the feature is applied. |
Available formats are listed below, you must prepend “TokenService.” to the format name, like these:
TokenService.RANDOM_TOKEN
TokenService.RANDOM_ALPHANUMERIC_TOKEN
TokenService.SEQUENTIAL_TOKEN
TokenService.LAST_FOUR_TOKEN
TokenService.FIRST_SIX_TOKEN
TokenService.FIRST_TWO_LAST_FOUR_TOKEN
TokenService.FIRST_SIX_LAST_FOUR_TOKEN
TokenService.FIXED_NINETEEN_TOKEN
TokenService.FIXED_TWENTY_LAST_FOUR_TOKEN
TokenService.EMAIL_ADDRESS_TOKEN
TokenService.DATE_MMDDYYYY_TOKEN
TokenService.DATE_DDMMYYYY_TOKEN
TokenService.DATE_YYYYMMDD_TOKEN
TokenService.FIRST_SIX_LAST_FOUR_FAIL_LUHN_TOKEN
TokenService.FIXED_FIRST_TWO_LAST_FOUR_FAIL_LUHN_TOKEN
TokenService.SHA2_256_BASE16_TOKEN
TokenService.SHA2_384_BASE16_TOKEN
TokenService.SHA2_512_BASE16_TOKEN
TokenService.SHA2_256_ BASE64_TOKEN
TokenService.SHA2_384_ BASE64_TOKEN
TokenService.SHA2_512_ BASE64_TOKEN
TokenService.ALPHANUMERIC_TOKEN
To learn more about these formats, see Token Formats.
The priority of the luhnCheck boolean in insert() and the luhnCheck integer in createNewFormat() vary, depending on their values, as can be seen in this image:
Returned Values
Returned string, string array, or two dimensional string arrays of token(s) created for the input value(s).
Exception
Throws TokenException if:
The table is missing.
The format is invalid.
The value is null or contains anything other than digits, white spaces, or dashes.
The value and customData arrays are not the same size.
A customData element is too long or too short.
Example
insert("1234567890123456", "CREDIT_CARD_NUMBERS",TokenService.LAST_FOUR_TOKEN, true)
The method does the following:
Searches the key table for the keys which is used by the token vault.
Requests the Key Manager for the encryption and hmac keys.
Creates the ciphertext and mac values, using the encryption and hmac keys.
Generates the token as per the token format rules and the luhn check setting.
Inserts the ciphertext, mac value, and token into the token vault.
Returns the token to the calling application.
