NAME
Crypt::CreditCard - 256-bit AES credit card encryption
SYNOPSIS
use Crypt::CreditCard;
my $ciphertext;
my $password = 'f00b@r'; # acquire from user
my $key;
{
# Encryption
my $card = Crypt::CreditCard->new();
$key = $card->key(); # generates key, suitable for a secure cookie
$card->number('5276440065421319') || die $card->errstr();
$card->cvv2('2345') || die $card->errstr(); # optional, may be omitted
$card->month('12') || die $card->errstr(); # optional, may be omitted
$card->year('03') || die $card->errstr(); # optional, may be omitted
$card->password($password);
$ciphertext = $card->encrypt() || die $card->errstr(); # store in db
}
{
# Decryption
my $card = Crypt::CreditCard->new();
$card->password($password); # acquire from user
$card->key($key); # acquire from a secure cookie
$card->decrypt($ciphertext) || die $card->errstr(); # get from db
my $number = $card->number(); # 5276440065421319
my $cvv2 = $card->cvv2(); # 2345
my $month = $card->month(); # 12
my $year = $card->year(); # 03
}DESCRIPTION
Note: You are advised to read the 'CAVEATS' section later in this document. Additionally, until this distribution reaches a non-developer (stable) release stage the interface and implementation may change at any time. It is therefore not recommended to make use of this distribution in a production environment until a non-developer release is made.
This module uses the United States Government's Advanced Encryption Standard (AES/Rijndael) with 256-bit keys to encrypt a credit card, and optionally a CVV2 number, expiration month and year. The encrypted representation, which includes all the given credit card components, is suitable for storing in a database field, e.g., TEXT (for the default datasize), or VARCHAR (if you manually decrease the datasize).
In order to encrypt, a password (something the user knows) and a key (something the user has) must first be specified. The password that the user uses to log into your service that requires secure credit card storage is usually what's used as the password. The password itself, if it's being stored in a databse, should ideally be encrypted using, say, SQL's PASSWORD(). The key is an automatically generated crytographically secure 256-bit randomly generated number. This key is suitable for storage in, say, a *secure* cookie.
Before a credit card number is encrypted, a check is made as to the validity of the credit card number using a mod-10 check. An error will be raised if the credit card number is invalid.
In the interest of heightened reliability and security an MD5 checksum is stored along with the credit card information, the key is xor'd against the password before being used as a basis for encryption, and the credit card information is padded with cryptographically secure data.
Assuming that someone built a machine that could crack a DES key in one second, it would still take that machine 149 trillion years to crack a 128-bit AES key. Crypt::CreditCard, by default, uses 256-bit keys.
PUBLIC METHODS
new
Constructor. Takes no arguments. Returns a credit card object.
errstr
Gets the error string (if applicable). See 'CAVEATS'.
key
Generates or sets a 256-bit (by default) crytographically secure number suitable for storage in, say, a secure cookie. This method is mandatory.
password
Sets the password that will be xor'd against the key prior to encryption. This method is mandatory.
keylength
Gets or sets the keylength, which must be one of: 128, 192 or 256. This method is optional, and by default is set to 256.
datasize
Gets or sets the datasize, which is usually one of: 128, 192 or 256. This method is optional, and by default is set to 256. The datasize must be a multiple of 32, and greater than or equal to 96.
strength
Gets or sets the strength of randomness (see Crypt::Random and CAVEATS). This is either /dev/random, /dev/urandom, or an alternative in /dev/. This method is optional, and by default is set to /dev/random.
cvv2
Gets or sets the cvv2 number. See: http://www.google.com/search?q=CVV2&ie=UTF-8&oe=UTF-8. This method requires a string representation of a number, not a number (see CAVEATS). This method is optional. If given, argument must be integral and between 3 and 4 digits.
month
Gets or sets the expiration month. This method requires a string representation of a number, not a number (see CAVEATS). This method is optional. If given, argument must be integral and either 1 or 2 digits.
year
Gets or sets the expiration year. This can be either, for example, "04" or "2004". This method requires a string representation of a number, not a number (see CAVEATS). This method is optional. If given, argument must be integral and either 2 or 4 digits.
number
Gets or sets the credit card number. The credit card must be valid or an error will be raised. This method requires a string representation of a number, not a number (see CAVEATS). This method is mandatory.
encrypt
Encrypts the credit card previously given and returns the ciphertext representation. The key(), number(), and password() methods must be called prior to calling encrypt().
decrypt
Decrypts the credit card information. Takes the ciphertext as an argument. The key(), and password() methods must be called prior to calling decrypt().
mode
Gets or sets the mode, which is one of the following (see Crypt::Rijndael for details):
ecb (electronic codebook mode), cbc (cipher block chaining, the default), cfb (128-bit cipher feedback), ofb (128-bit output feedback), ctr (counter mode).
This is optional and defaults to cipher block chaining mode.
iv
Gets or sets the initial vector (see Crypt::Rijndael for details).
PRIVATE METHODS
_pack_cc
_unpack_cc
_pad_missing
Pads cvv2, month, and year with random cryptographically secure data if they were not given.
_is_string
Returns 1 if the argument was a string, 0 otherwise.
_validate
Returns true if the mod10 passes for the credit card.
_pad
Generates an amount of crytographically secure padding based upon the datasize by calling gen_pad().
_gen_pad
Generates 32 bits of crytographically secure padding.
_kill
Renders the object passed to it unusable for future operations.
CAVEATS
The methods: number(), cvv2(), month(), and year() *MUST* be passed string arguments, not numeric arguments. This means that, for example, you must do $card->number('5276440065421319'), and not $card->number(5276440065421319). If you attempt to call any of the above methods with numeric arguments, Crypt::CreditCard will detect it and generate an error.
An object reference is rendered unusuable for any further access after an encrypt() is called against it. This is a security feature.
By default, strength() is set to use /dev/random, however IF YOU DON'T DESIRE BLOCKING AND DECREASED SPEED FOR THE PURPOSE OF MORE RANDOM DATA, CONSIDER SETTING strength() TO USE /dev/urandom. The following excerpt from Crypt::Random states, "The /dev/random driver maintains an estimate of true randomness in the pool and decreases it every time random strings are requested for use. When the estimate goes down to zero, the routine blocks and waits for the occurrence of non-deterministic events to refresh the pool. When the routine is blocked, Crypt::Random's read() will be blocked till desired amount of random bytes have been read off of the device. The /dev/random kernel module also provides another interface, /dev/urandom, that does not wait for the entropy-pool to recharge and returns as many bytes as requested. For applications that must not block (for a potentially long time) should use /dev/urandom. /dev/random should be reserved for instances where very high quality randomness is desired. If there's a hardware random number generator available, for instance the Intel i8x0 random number generator, please use it instead of /dev/random! It'll be high quality, a lot faster and it won't block! Usually your OS will provide access to the RNG as a device, eg (/dev/intel_rng)."
IN ORDER TO BE GUARANTEED NOMINAL OPERATION, YOU MUST check for errstr() on the following methods: mode(), strength(), keylength(), datasize(), encrypt(), and decrypt(). Additionally, you must check for errstr() on the following methods, but *only* when you are assigning to them: cvv2(), month(), year(), number().
BUGS
Please report any bugs to (patches welcome):
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Crypt-CreditCardCOPYRIGHT
Copyright (c) 2003 Adam J. Foxson. All rights reserved.
Copyright (c) 2003 Marty Pauley. All rights reserved.LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
SEE ALSO
AUTHORS
Adam J. Foxson <afoxson@pobox.com>, with patches from Marty Pauley at <kasei@cpan.org>.