班级清单

FastSitePHP\Security\Crypto

FastSitePHP Crypto Class

This is a helper class using a Facade Software Design Pattern to simplify Secure Encryption, Data Signing, and JWT usage.

This class allows for only the default secure settings of each object and requires secure keys to be defined in either the App Config Array or as Environment Variables.

By default Signed Data and JSON Web Tokens are valid for 1 hour and expire after. The expiration time can be changed from a parameter when calling either [sign()] or [encodeJWT].

Example usage:
    $app->config['ENCRYPTION_KEY'] = 'dd8daccb9e2b66321a......';
    $encrypted_text = Crypto::encrypt($data);
    $decrypted_data = Crypto::decrypt($encrypted_text);

[$app] Config (or Environment Variables) Settings:
    ENCRYPTION_KEY
        encrypt()
        decrypt()
        encryptFile()
        decryptFile()
    SIGNING_KEY
        sign()
        verify()
    JWT_KEY
        encodeJWT()
        decodeJWT()

源代码

示例代码

Security - Encrypt and Decrypt Data

// Generate a Key for Encryption.
// The key is a long hex string of secure random bytes.
// The key would typically be saved with your app or in config.
$crypto = new \FastSitePHP\Security\Crypto\Encryption();
$key = $crypto->generateKey();

// Encrypt and Decrypt using the Crypto Helper Class with Config Settings.
// Data of different data types can be encrypted and returned in the
// same format (string, int, object, etc).
$app->config['ENCRYPTION_KEY'] = $key;
$encrypted_text = \FastSitePHP\Security\Crypto::encrypt($data);
$decrypted_data = \FastSitePHP\Security\Crypto::decrypt($encrypted_text);

// Encrypt and Decrypt using the Encryption Class. This class
// provides many additional options that are not in the helper class.
$encrypted_text = $crypto->encrypt($data, $key);
$decrypted_data = $crypto->decrypt($encrypted_text, $key);

Security - Encrypt and Decrypt a File

// FastSitePHP allows for fast authenticated encryption of any size file
// (even large files that are many gigs in size). The code used for encryption
// is compatible with shell commands and a Bash Script [encrypt.sh] that works
// on Linux and Unix Computers. The Bash Script can be downloaded from this site,
// and will work on most Linux OS's without having to install anything.

// Generate a Key for Encryption
$crypto = new \FastSitePHP\Security\Crypto\FileEncryption();
$key = $crypto->generateKey();

// Build file paths of files to save based on the original name
$enc_file = $file_path . '.enc';
$output_file = $enc_file . '.decrypted';

// Encrypt and Decrypt using the Crypto Helper Class with Config Settings.
// A [FileEncryption] class also exists with additional options.
$app->config['ENCRYPTION_KEY'] = $key;
\FastSitePHP\Security\Crypto::encryptFile($file_path, $enc_file);
\FastSitePHP\Security\Crypto::decryptFile($enc_file, $output_file);

Security - Encode and Decode a JSON Web Token (JWT)

// The JWT Payload can be either an Object or an Array (Dictionary).
$payload = [
    'User' => 'John Doe',
    'Roles' => ['Admin', 'SQL Editor']
];

// Generate a Key for Encoding (Signing).
// The key is a long hex string of secure random bytes.
// The key would typically be saved with your app or in config.
$jwt = new \FastSitePHP\Security\Crypto\JWT();
$key = $jwt->generateKey();

// Encode and Decode JWT with the Crypto Helper Class with Config Settings.
// When using the default parameters with the helper class the data has a
// 1-hour timeout.
$app->config['JWT_KEY'] = $key;
$token = \FastSitePHP\Security\Crypto::encodeJWT($payload);
$data  = \FastSitePHP\Security\Crypto::decodeJWT($token);

// Encode (Sign) and Decode (Verify) using the JWT Class. When using
// default settings with the JWT Class, not timeout is specified, all
// claims are validated, and a secure key is required.
$token = $jwt->encode($payload, $key);
$data  = $jwt->decode($token, $key);

// Add Claims to the Payload and use an Insecure Key for Compatibility
// with other sites (Often online demos of JWT are shown using simple
// passwords for the key). By default keys are required to be secure
// with proper length and in either Base64 or Hex format.

$payload = $jwt->addClaim($payload, 'exp', '+10 minutes');
$payload = $jwt->addClaim($payload, 'iss', 'example.com');

$jwt
    ->useInsecureKey(true)
    ->allowedIssuers(['example.com']);

$insecure_key = 'password123';
$token = $jwt->encode($payload, $insecure_key);
$data  = $jwt->decode($token, $insecure_key);

Security - Sign and Verify Data

// Using the [SignedData] is similar in concept to using JWT.
// A client can read the data but not modify it.

// Generate a Key for Signing.
// The key is a long hex string of secure random bytes.
// The key would typically be saved with your app or in config.
$csd = new \FastSitePHP\Security\Crypto\SignedData();
$key = $csd->generateKey();

// Sign and Verify using the Crypto Helper Class with Config Settings.
// When using the default parameters with the helper class the data has
// a 1-hour timeout. Data of different data types can be signed and
// verified to the original format (string, int, object, etc).
$app->config['SIGNING_KEY'] = $key;
$signed_text   = \FastSitePHP\Security\Crypto::sign($data);
$verified_data = \FastSitePHP\Security\Crypto::verify($signed_text);

// Sign and Verify using the SignedData Class. The SignedData Class
// allows for additional options and doesn't use config settings.
// The parameter [$expire_time] is optional.
$expire_time   = '+20 minutes';
$signed_text   = $csd->sign($data, $key, $expire_time);
$verified_data = $csd->verify($signed_text, $key);

方法

`encrypt($data)`

静态功能

Encrypt data (string, int, float, bool, object, or array) and return the encrypted text as a base64-url string.

返回类型: string

`decrypt($encrypted_text)`

静态功能

Decrypt data that was encrypted using the [encrypt()] function and return the original value.

The same data type is returned so if a string was encrypted a string will be returned and if an array was encrypted then an array will be returned. Objects of type stdClass or custom classes that were encrypted are returned as an Array (Dictionary).

If decryption fails then null will be returned.

返回类型: mixed

`sign($data, $expire_time = '+1 hour')`

静态功能

Sign data (string, int, float, bool, object, or array) and return the signed data in one of the following formats:
'base64url(data).type.base64url(signature)'
'base64url(data).type.timestamp.base64url(signature)'

The default expiration time is 1 hour; this can be changed to a different time or turned off passing [null].

返回类型: string

`verify($signed_text)`

静态功能

Verify data that was signed using the [sign()] function and return the original value.

The same data type is returned so if a string was signed a string will be returned and if an array was signed then an array will be returned. Objects of type stdClass or custom classes that were signed are returned as an Array (Dictionary).

If verification fails then null will be returned.

返回类型: mixed

`encryptFile($file_path, $enc_file)`

静态功能

Encrypt a file

If a file is 10 MB or smaller (or any size on Windows) then it will be processed in memory, otherwise the file will be processed using shell commands. This allows for files of any size to be encrypted.

If you need to encrypt files that are larger than 2 GB on a 32-Bit OS then you should use the [FileEncryption] class directly like this:
    $crypto = new FileEncryption();
    $crypto->processFilesWithCmdLine(true);
    $crypto->encryptFile($file_path, $enc_file, $key);

`decryptFile($enc_file, $output_file)`

静态功能

Decrypt a file that was created from [encryptFile()]. The same memory and OS rules apply for file processing.

This function has no return value so if decryption fails an exception is thrown.

`encodeJWT($payload, $exp_time = '+1 hour')`

静态功能

Create a JSON Web Token (JWT) with a default expiration time of 1 hour.

返回类型: string

`decodeJWT($token)`

静态功能

Decode and Verify a JWT. If the token is not valid null will be returned.

返回类型: array | null - The payload that was originally encoded.