README

帮助配置和使用加密方案的库。

目的

此库是为了使管理加密数据更简单而创建的，包括获取加密密钥、旋转密钥、使用不同的加密算法以及更好地跟踪哪些数据与密钥组合加密。

用法

基本

要开始，您至少需要定义一个密钥源和一个配置文件。

配置文件是您告诉加密器要使用哪种加密算法以及要使用哪个密钥进行加密/解密的方式。密钥源是负责根据名称加载密钥的类。

简单示例。

<?php

use Giftcards\Encryption\EncryptorBuilder;

$encryptor = EncryptorBuilder::newInstance()
    ->addKeySource('array', array('keys' => array('foo' => 'bar', 'none' => '')) //array source just takes the array of keys you give it and uses
                                                                                 //that to return the key on request
    ->setProfile('default', 'foo', 'mysql_aes')
    ->setProfile('no_op', 'none', 'no_op')
    ->setDefaultProfile('default')
    ->build()
;

$encrypted1 = $encryptor->encrypt('baz');//this will use the default profile
$encrypted2 = $encryptor->encrypt('baz', 'default'); //this will too
$encrypted3 = $encryptor->encrypt('baz', 'no_op'); //this will use the no_op profile
$decrypted1 = $encryptor->decrypt($encrypted1); //the encrypted data is actually an object
                                                //which can be cast to a string
                                                //that holds the encrypted text plus the profile 
                                                //used so you dont need to put the profile
$decrypted1 = $encryptor->decrypt($encrypted2, 'default');//you can also tell the encryptor which profile you want to use
$decrypted1 = $encryptor->decrypt($encrypted3, 'default');//you could even tell it to use a different profile than what was used
                                                          //to encrypt the data

如果您没有设置默认配置文件，则在加密时始终需要传递配置文件名称。然而，在解密时，由于它将执行相同的工作以尝试确定加密时使用的配置文件，因此也会有相同的要求。

深入了解

加密算法

加密算法是遵循Giftcards\Encryption\Cipher\CipherInterface的类。它们定义了加密/解密数据的不同方式。当前实现包括：

mysql_aes - 此算法与 mysql/mariadb 中的 AES_ENCRYPT/AES_DECRYPT 函数相似
no_op - 此算法只是一个传递，它将直接返回加密/解密的数据

密钥源

密钥源是遵循Giftcards\Encryption\Key\SourceInterface的类。它们定义了加密器加载密钥的方式。它们通过名称获取密钥，如果找到则返回密钥，如果没有找到则抛出异常。当前实现包括：

ArraySource - 此算法接受一个键名值对的键数组
CachingSource - 此算法接受另一个源并将其缓存，以便缓存密钥请求
CombiningSource - 此源允许您从两个其他密钥中创建一个新密钥。它接受一个包含新键名称和每个值的数组，值是新密钥的左右部分所使用的键的名称
ChainSource - 接受密钥源链并返回第一个具有给定名称值的密钥
ContainerAwareChainSource - 此源与 ChainSource 的工作方式相同，但它接受一个 symfony 容器，允许您将服务名称作为密钥源，以便仅在请求密钥时加载它们
CircularGuardSource - 此源接受一个要包装的源，如果您设置密钥源以可能相互引用并且您认为它们可能具有无限循环密钥请求的可能性，则它会跟踪通过它请求的密钥。如果请求相同的密钥，它将在 has 返回 false 并抛出密钥未找到异常之前不询问其内部源
ContainerParametersSource - 此算法接受一个 symfony 容器并查找与请求的密钥名称相同的参数
FallbackSource - 此算法接受一个密钥名称数组和它们不存在时的回退数组，并在抛出异常之前遍历所有回退
IniFileSource - 此算法接受 ini 文件的路径并使用 ini 文件的键加载密钥
MappingSource - 此算法允许您别名键。它接受一个新键名称作为键和要映射到的键的值作为值的数组
mongoSource - 该源允许您将Mongo集合定义为键源。它使用您定义的搜索字段通过名称搜索键
NoneSource - 这是一种简单的方法，可以添加一个名为 none 的键
PrefixKeyNameSource - 该源允许您封装不同的源并为它定义一个前缀。如果您使用链，这将非常有用。例如，您可以将Mongo源封装起来，并指定它只响应以 mongo: 前缀的键（冒号是默认分隔符，可配置）
VaultSource - 该源允许您定义一个从密钥库中提取密钥的源

配置文件

配置文件是一种将加密算法与密钥名称分组的方法。加密器使用配置文件来决定如何加密/解密数据。它只包含密钥的名称和要使用的加密算法的名称

密文

密文旨在表示已加密的数据。加密器返回一个可转换为字符串的实例，它将自动使用稍后提到的序列化程序进行序列化。这个想法是允许加密数据和用于加密它的配置文件一起移动

密文序列化/反序列化器

密文序列化程序和反序列化程序负责将密文实例转换为字符串以便易于存储，并在加密器解密之前进行反序列化。这允许它们轻松存储，并使加密器能够仅处理包含如何解密信息的密文。有两个接口 Giftcards\Encryption\CipherText\Serializer\SerializerInterface 和 Giftcards\Encryption\CipherText\Serializer\DeserializerInterface，还有一个组合接口 SerializerDeserializerInterface，加密器实际使用它。分离接口允许不同的序列化和反序列化方式。当前实现包括

BasicSerializerDeserializer - 将配置文件转换为数组，将其JSON编码，然后将其base64编码，并将其与base64编码的加密数据连接在一起以形成一个长字符串。在反序列化方面执行相反的操作
NoProfileSerializerDeserializer - 该返回加密数据的作为序列化密文的内容。它只会对具有与其构造函数中发送的配置文件匹配的配置文件的密文执行此操作。这增加了一点点安全性，因为在序列化时配置文件信息会丢失，并且必须推断与发送到序列化器构造函数的相同。在反序列化时（如上所述），它将加密数据作为是并使用它和传递给其构造函数的配置文件创建一个密文
ChainSerializerDeserializer - 该接受一系列序列化程序和一系列反序列化程序，并将密文传递给第一个可以处理它的程序
ContainerAwareChainSerializerDeserializer - 该与链执行相同的功能，但它在构造函数中接受一个symfony容器，并可以通过您提供的服务名称提取序列化程序/反序列化程序

密文旋转器

这些类允许以编程方式定义您需要旋转加密密钥或加密算法的位置，以便您只需保持一个列表并在需要旋转时遍历它们，在调用旋转时，可以提供一个可选的新配置文件来使用（如果没有使用新配置文件，则将使用当前默认的加密器配置文件来重新加密）。它允许您定义例如一系列表以及需要密钥旋转的特定列。所有旋转器都必须遵循接口 Giftcards\Encryption\CipherText\Rotator\RotatorInterface。当前实现包括

数据库表旋转器 - 该类接收PDO实例、表名、该表中的字段以及用于标识行的方式（通常是主键），并在请求时旋转这些字段。
DoctrineDBAL旋转器 - 该类使用相同的数据，但您需要提供一个Doctrine DBAL连接，而不是PDO实例。

Doctrine ORM集成

您可以使用监听器和注解来定义具有加密字段的实体。它们将在加载时自动解密，在刷新时加密。您可以在注解中定义要使用的配置文件。如果没有定义，将使用默认配置文件。您还可以使用ignoredValues选项在注解中定义要忽略的值数组。默认值为array(null)。

构建器

有一些构建器类旨在封装旋转器、序列化器、反序列化器和密钥源的创建。

这允许您调用addKeySource($source, $options, $prefix, $addCircularGuard)来添加密钥源，内部构建器会为您处理工作。您可以调用addSerializer($serializer, $options)、addDeserializer($deserializer, $options)。还有一个独立的旋转器构建器，因为它们不用于加密器。

加密器构建器可以使用EncryptorBuilder::newInstance()实例化。

加密器构建器使用许多子构建器。

Giftcards\Encryption\Key\Source\SourceBuilder - 构建密钥源
Giftcards\Encryption\CipherText\Serializer\SerializerDeserializerBuilder - 构建序列化和反序列化的链

旋转器构建器是Giftcards\Encryption\CipherText\Rotator\RotatorBuilder。

所有这些子构建器都依赖于一个工厂，该工厂为它创建的每种类型都保存一个构建器。它们可以在各自的目录下找到。它们允许它们根据给定的$name、$options组合来构建，而不仅仅是实例。

以下构建器列表中的名称可以传递给构建器的第一个参数，之后命名的选项应作为选项数组传递。例如，对于名为foo的构建器，其选项为array('bar' => 'baz')，您可以在加密器构建器上调用addKeySource('foo', array('bar' => 'baz')，或者在密钥源构建器上调用add('foo', array('bar' => 'baz')。对其他构建器也是如此。

密钥源构建器

数组

keys - 创建数组源所需的密钥数组，键是密钥名称，值是密钥值

container_parameter

container - 要传递给源的症状容器。这可能取决于您如何实例化此构建器。如果您传递了容器，则此选项不是必需的

ini_file

file - ini文件的路径
case_sensitive - 是否在调用时对密钥进行大小写敏感

mongo

connection - 要使用的mongo连接。这可以是doctrine/mongodb连接的实例，或是一个包含以下键的数组以创建一个：'server', 'options', 'configuration', 'event_manager'（除了server之外都是必需的）。
database - 要使用的数据库
collection - 要使用的集合
find_by_field - 用于查找正确文档的字段。例如，如果字段是name，它将尝试找到一个具有与密钥名称匹配的name字段的文档
value_field - 在找到文档时提取的字段值。例如，如果value_field是value，则将value字段作为密钥的值提取

vault

base_url - vault的主域名 + 协议URL
token - 用于请求vault的令牌
mount - 要请求的mount
value_field - 用于提取键值的字段。例如，如果 value_field 是 value，则它将提取 value 字段作为键的值
api_version - API 版本默认为 v1。

序列化/反序列化构建器

基本

分隔符 - 用于将 base64 编码的配置文件数据与 base64 编码的加密数据结合使用的分隔符字符串

no_profile

profile - 在序列化和反序列化加密文本之前要检查的配置文件，以及要在反序列化时设置的配置文件。这可以是 Giftcards\Encryption\Profile\Profile 的一个实例，或者如果您将配置文件注册传递给其构造函数，您可以提供一个配置文件名称

礼品卡 / 加密

维护者

详细信息