Crypt 组件¶

概览¶

注意

需要 PHP 的openssl扩展存在于系统中

注意

DOES NOT支持不安全的带模式的算法：

des*, rc2*, rc4*, des*, *ecb

Phalcon 通过Phalcon\Encryption\Crypt组件提供加密功能。该类为 PHP 的openssl加密库提供了简单的面向对象封装。

默认情况下，该组件使用AES-256-CFB加密算法。

AES-256 加密算法被广泛用于互联网上的 SSL/TLS 协议。它被认为是顶级加密算法之一。从理论上讲，它是不可破解的，因为密钥组合的数量非常庞大。尽管美国国家安全局 (NSA) 将其归类为Suite B，但他们也建议使用大于 128 位的密钥进行加密。

注意

必须使用与当前算法相对应的密钥长度。对于默认算法aes-256-cfb默认密钥长度为 32 字节。

基本用法¶

该组件设计得非常易于使用：

<?php

use Phalcon\Encryption\Crypt;

$key = "12345";

$crypt     = new Crypt();
$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

echo $crypt->decrypt($encrypted, $key);

如果在构造函数中未传递任何参数，组件将默认使用aes-256-cfb加密算法并启用签名。你始终可以更改加密算法以及禁用签名。

注意

构造函数还接受一个用于签名请求的参数。对于 v5，此参数的默认值已更改为true

注意

构造函数现在接受一个Phalcon\Encryption\Crypt\PadFactory作为第三个参数。如果没有指定，则会为你创建一个Phalcon\Encryption\Crypt\PadFactory对象。

<?php

use Phalcon\Encryption\Crypt;
use Phalcon\Encryption\Crypt\PadFactory;

$key = "12345";

$padFactory = new PadFactory();
$crypt      = new Crypt("aes-256-cfb", true, $padFactory);

$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

echo $crypt->decrypt($encrypted, $key);

<?php

use Phalcon\Encryption\Crypt;

$key   = "12345";
$crypt = new Crypt();

$crypt
    ->setCipher('aes256')
    ->useSigning(false)
;

$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

echo $crypt->decrypt($encrypted, $key);

加密¶

The encrypt()方法用于加密字符串。该组件将使用在构造函数中或显式设置的先前设置的加密算法。如果参数中未传递key，则将使用先前设置的密钥。

<?php

use Phalcon\Encryption\Crypt;

$key   = "12345"; 
$crypt = new Crypt();
$crypt->setKey($key);

$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text);

或者将密钥作为第二个参数使用

<?php

use Phalcon\Encryption\Crypt;

$key       = "12345"; 
$crypt     = new Crypt();
$text      = 'This is the text that you want to encrypt.';
$encrypted = $crypt->encrypt($text, $key);

该方法默认情况下也会内部使用签名。你可以在方法调用前始终使用useSigning(false)来禁用它。

注意

如果你选择与ccm或gcm相关的加密算法，你还必须为它们提供authData。否则将抛出异常。

解密¶

The decrypt()方法用于解密字符串。类似于encrypt()该组件将使用在构造函数中或显式设置的先前设置的加密算法。如果参数中未传递key，则将使用先前设置的密钥。

<?php

use Phalcon\Encryption\Crypt;

$key   = "12345"; 
$crypt = new Crypt();
$crypt->setKey($key);

$text      = 'T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3';
$encrypted = $crypt->decrypt($text);

或者将密钥作为第二个参数使用

<?php

use Phalcon\Encryption\Crypt;

$key   = "12345"; 
$crypt = new Crypt();
$crypt->setKey($key);

$text      = 'T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3';
$encrypted = $crypt->decrypt($text, $key);

该方法默认情况下也会内部使用签名。你可以在方法调用前始终使用useSigning(false)来禁用它。

Base64 加密¶

The encryptBase64()可以用于以 URL 友好的方式加密字符串。它内部使用encrypt()并接受text以及可选的key要加密的元素。还有一个第三个参数safe（默认值为false）将对非 URL友好的字符（例如+或/.

Base64 解密¶

The decryptBase64()可以用于以 URL 友好的方式解密字符串。类似于encryptBase64()它内部使用decrypt()并接受text以及可选的key要加密的元素。还有一个第三个参数safe（默认值为false）将对之前替换过的非 URL友好的字符（例如+或/.

异常¶

在Phalcon\Encryption\Crypt组件中抛出的异常将是 [Phalcon\Encryption\Crypt\Exception][config-exception] 类型。但是，如果你正在使用签名并且计算出的哈希值与decrypt()不匹配，Phalcon\Encryption\Crypt\Mismatch将会被抛出。你可以使用这些异常来有选择地捕获仅从此组件抛出的异常。

<?php

use Phalcon\Encryption\Crypt\Mismatch;
use Phalcon\Mvc\Controller;

class IndexController extends Controller
{
    public function index()
    {
        try {
            // Get some configuration values
            $this->crypt->decrypt('hello');
        } catch (Mismatch $ex) {
            echo $ex->getMessage();
        }
    }
}

功能¶

加密算法¶

gettergetCipher()返回当前选定的加密算法。如果没有明确定义（无论是通过 settersetCipher()还是对象的构造函数），则默认选择aes-256-cfb。首选的aes-256-gcm是加密算法。

你总是可以通过调用getAvailableCiphers().

哈希算法¶

gettergetHashAlgo()返回组件使用的哈希算法。如果未通过 settersetHashAlgo()超全局变量。如果cookie存在于任一集合中，则返回sha256明确定义，则将使用默认值。如果所定义的哈希算法在系统中不可用或错误，将抛出 [Phalcon\Encryption\Crypt\Exception][crypt=exception]。

你总是可以通过调用getAvailableHashAlgos().

密钥¶

该组件提供了一个 getter 和一个 setter 用于设置要使用的密钥。一旦设置了密钥，它将用于任何加密或解密操作（前提是使用这些方法时未定义key参数）。

getKey()：返回加密密钥。
setKey()设置加密密钥。

注意

你应该始终尽可能创建最安全的密钥。12345可能适合你的行李组合，或者password1适用于你的电子邮件，但对于你的应用程序，你应该尝试使用更复杂的东西。密钥越长且越随机越好。当然，密钥的长度取决于所选的加密算法。

许多在线服务可以生成可用于密钥的随机强文本。或者，你始终可以使用来自hash()方法的Phalcon\Security组件，它可以通过哈希字符串提供一个强密钥。

签名¶

为了指示组件是否使用签名，useSigning可用。它接受一个布尔值，内部设置一个标志，指定是否使用签名。

验证数据¶

如果所选的加密算法是类型gcm或ccm（加密算法名称以什么结尾），那么组件正确加密或解密数据需要验证数据。为此操作提供的方法是：

setAuthTag()
setAuthData()
setAuthTagLength()-16)

填充¶

您还可以通过使用setPadding(). 默认情况下，该组件将使用PADDING_DEFAULT. 可用的填充常量是：

PADDING_ANSI_X_923
PADDING_DEFAULT
PADDING_ISO_10126
PADDING_ISO_IEC_7816_4
PADDING_PKCS7
PADDING_SPACE
PADDING_ZERO

依赖注入¶

与大多数 Phalcon 组件一样，您可以将Phalcon\Encryption\Crypt对象存储在您的Phalcon\Di容器中。这样做后，您将能够从控制器、模型、视图以及实现Injectable.

注册。下面是一个注册服务以及访问它的示例：

<?php

use Phalcon\Di\FactoryDefault;
use Phalcon\Encryption\Crypt;

// Create a container
$container = new FactoryDefault();

$container->set(
    'crypt',
    function () {
        $crypt = new Crypt();

        // Set a global encryption key
        $crypt->setKey(
            "T4\xb1\x8d\xa9\x98\x05\\\x8c\xbe\x1d\x07&[\x99\x18\xa4~Lc1\xbeW\xb3"
        );

        return $crypt;
    },
    true
);

该组件现在可以通过crypt键名在你的控制器中使用

<?php

use MyApp\Models\Secrets;
use Phalcon\Encryption\Crypt;
use Phalcon\Http\Request;
use Phalcon\Mvc\Controller;

/**
 * @property Crypt   $crypt
 * @property Request $request
 */
class SecretsController extends Controller
{
    public function saveAction()
    {
        $secret = new Secrets();

        $text = $this->request->getPost('text');

        $secret->content = $this->crypt->encrypt($text);

        if ($secret->save()) {
            $this->flash->success(
                'Secret was successfully created!'
            );
        }
    }
}

常量¶

提供了两个常量：

DEFAULT_ALGORITHM = "sha256"
DEFAULT_CIPHER = "aes-256-cfb"
PADDING_ANSI_X_923 = 1
PADDING_DEFAULT = 0
PADDING_ISO_10126 = 3
PADDING_ISO_IEC_7816_4 = 4
PADDING_PKCS7 = 2
PADDING_SPACE = 6
PADDING_ZERO = 5

您可以在项目中使用它们，或者如果需要实现自己的类，则可以覆盖它们。

方法¶

public function __construct(
    string $cipher = self::DEFAULT_CIPHER, 
    bool $useSigning = true, 
    PadFactory $padFactory = null
)

构造函数

public function decrypt(string $input, string $key = null): string

解密加密文本

public function decryptBase64(
    string $input, 
    string $key = null, 
    bool $safe = false
): string

解密一个编码为base64字符串

public function encrypt(string $input, string $key = null): string

加密文本

public function encryptBase64(
    string $input, 
    string $key = null, 
    bool $safe = false
): string

加密文本并以base64字符串

public function getAvailableCiphers(): array

返回可用密码列表

public function getAuthData(): string

返回身份验证数据

public function getAuthTag(): string

返回身份验证标签

public function getAuthTagLength(): int

返回身份验证标签长度

public function getAvailableHashAlgorithms(): array

返回适用于hash_hmac

public function getHashAlgorithm(): string

获取哈希算法的名称。

public function getCipher(): string

返回当前密码

public function getKey(): string

返回加密密钥

public function isValidDecryptLength(string $input): bool

返回解密输入长度是否有效（密码所需的字节数）

public function setAuthData(string $data): CryptInterface

设置身份验证数据

public function setAuthTag(string $tag): CryptInterface

设置身份验证标签

public function setAuthTagLength(int $length): CryptInterface

设置身份验证标签长度

public function setCipher(string $cipher): CryptInterface

设置用于数据加密和解密的密码算法

public function setKey(string $key): CryptInterface

public function setHashAlgorithm(string $hashAlgorithm): CryptInterface

设置哈希算法的名称。

public function setPadding(int $scheme): CryptInterface

设置填充方案

public function useSigning(bool $useSigning): CryptInterface

使用消息摘要（签名）或不使用

PadFactory¶

The Phalcon\Encryption\Crypt\PadFactory是一个实例化类的对象，这些类用于在加密或解密期间填充和解除数据。

名称	类
`ansi`	`Phalcon\Encryption\Crypt\Padding\Ansi`
`iso10126`	`Phalcon\Encryption\Crypt\Padding\Iso10126`
`isoiek`	`Phalcon\Encryption\Crypt\Padding\IsoIek`
`noop`	`Phalcon\Encryption\Crypt\Padding\Noop`
`pjcs7`	`Phalcon\Encryption\Crypt\Padding\Pkcs7`
`space`	`Phalcon\Encryption\Crypt\Padding\Space`
`zero`	`Phalcon\Encryption\Crypt\Padding\Zero`

Phalcon\Encryption\Crypt\Padding\PadInterface也已提供，如果您需要创建自己的填充策略，请注意，您需要在Phalcon\Encryption\Crypt\PadFactory中注册新的填充类，并将其注入到Phalcon\Encryption\Crypt组件定义的。