README

SecureProps是一款强大的PHP库，旨在简化对象属性数据的加密和解密。

利用PHP属性的强大功能，SecureProps允许开发者在应用程序中轻松地保护敏感数据。该库支持非对称和对称加密方法，为保护应用程序数据提供了灵活性。

功能

• PHP对象中属性加密和解密的简单易用性。
• 支持使用RSA密钥进行非对称加密。
• 支持使用高级加密标准（AES-256-GCM）进行对称加密。

要求

• PHP 8.0或更高版本。
• 在您的PHP安装中启用OpenSSL扩展。

安装

您可以通过运行以下命令使用Composer安装SecureProps：

composer require ilicmiljan/secure-props

确保您的composer.json文件已更新，并将库包含在项目的依赖项中。

用法

标记属性进行加密

使用#[Encrypted]属性标记要加密的属性。此属性支持可选的placeholder参数，用于自定义解密失败处理。

当解密失败且提供了placeholder时，将使用该值。如果占位符为null，可能会抛出异常。

use IlicMiljan\SecureProps\Attribute\Encrypted;

class User
{
    #[Encrypted(placeholder: "***-**-****")]
    private string $socialSecurityNumber;

    #[Encrypted]
    private string $secretNote;
}

加密和解密对象

要加密或解密对象，您需要使用ObjectEncryptionService。以下是一个示例

use IlicMiljan\SecureProps\ObjectEncryptionService;
use IlicMiljan\SecureProps\Cipher\AdvancedEncryptionStandardCipher;

// Create a cipher instance (AES in this example)
$cipher = new AdvancedEncryptionStandardCipher('256-BIT-KEY-HERE');

// Initialize the encryption service with a runtime object properties reader
$encryptionService = new ObjectEncryptionService($cipher, new RuntimeObjectPropertiesReader());

$user = new User();
$user->setSocialSecurityNumber('123-45-6789');

// Encrypt properties
$encryptedUser = $encryptionService->encrypt($user);

// Decrypt properties
$decryptedUser = $encryptionService->decrypt($encryptedUser);

非对称加密

要使用非对称加密，请使用您的公钥和私钥初始化AsymmetricEncryptionCipher

use IlicMiljan\SecureProps\Cipher\AsymmetricEncryptionCipher;

$cipher = new AsymmetricEncryptionCipher($publicKey, $privateKey);

// Then, pass this cipher to the ObjectEncryptionService as shown above.

标签加密

当处理具有加密和非加密值的属性的对象时，TagAwareCipher提供了一种高级解决方案。此加密器允许目标解密，仅对加密和标记的属性进行操作，这可以防止遇到非加密数据时出错。

工作原理

TagAwareCipher自动使用<ENC>和</ENC>标签标记加密数据，使其易于识别。在解密过程中，它专门查找这些标签以确定要解密的数据。这种目标方法意味着如果对象包含标记（加密）和未标记（纯文本）数据，TagAwareCipher将仅尝试解密标记的部分。

这避免了尝试解密未加密数据时通常会遇到的异常风险，确保处理无错误。

重要

当使用TagAwareCipher进行解密时，重要的是要理解它只会解密带有<ENC>和</ENC>标签的数据。

如果它遇到没有这些标签的加密数据，解密过程将跳过它，数据将以加密形式返回。

以下是一个示例

// Initialize the base cipher with AES encryption.
// Optionally, attach a NullEncoder to prevent data double-encoding. Useful when
// the decorator cipher (e.g., TagAwareCipher) applies its own encoding.
$baseCipher = new AdvancedEncryptionStandardCipher('256-BIT-KEY-HERE', new NullEncoder());

// Initialize TagAwareCipher with your base cipher and an optional custom encoder.
$cipher = new TagAwareCipher($baseCipher, new Base64Encoder());

// Initialize the encryption service with a runtime object properties reader.
$encryptionService = new ObjectEncryptionService($cipher, new RuntimeObjectPropertiesReader());

$user = new User();
$user->setSocialSecurityNumber('123-45-6789');

// Encrypt properties
$encryptedUser = $encryptionService->encrypt($user);

// Decrypt properties
$decryptedUser = $encryptionService->decrypt($encryptedUser);

属性读取器

SecureProps提供了两种类型的属性读取器，以高效地处理PHP对象中的加密属性：RuntimeObjectPropertiesReader和CachingObjectPropertiesReader。

RuntimeObjectPropertiesReader

RuntimeObjectPropertiesReader在运行时动态检查对象，以识别带有#[Encrypted]属性的属性。利用PHP的反射不需要额外的缓存设置，并提供简单的检查功能。

CachingObjectPropertiesReader

为了提高性能，特别是在频繁处理相同类型对象的程序中，CachingObjectPropertiesReader 会缓存属性读取结果。这种方法减少了与反射相关的计算开销。

它可以与符合 PSR-6 标准的缓存解决方案无缝集成，允许进行可定制的性能优化。

快速入门示例

将 CachingObjectPropertiesReader 与 RuntimeObjectPropertiesReader 和符合 PSR-6 标准的缓存实现相结合

// Initialize a PSR-6 cache pool
$cache = new FilesystemAdapter(...);

// Configure the caching reader
$reader = new CachingObjectPropertiesReader(
    new RuntimeObjectPropertiesReader(),
    new CacheItemPoolAdapter($cache)
);

// Set up the ObjectEncryptionService with the reader
$encryptionService = new ObjectEncryptionService($cipher, $reader);

编码器

编码器在加密和解密过程中是关键组件，将数据转换为适合安全传输或存储的格式，然后再将其转换回原始形式。

Base64编码器

Base64Encoder 被设计用于将二进制数据编码成ASCII字符的字符串，使用Base64编码方案。这使得数据可以在不安全的二进制协议中安全传输。

Null编码器

NullEncoder 作为透传使用，这意味着它不会改变输入数据。这在您想避免对已经以适合存储的格式存在的数据进行双重编码时特别有用，或者当编码过程由其他地方管理时。

快速入门示例

在初始化具有AES加密的 AdvancedEncryptionStandardCipher 的上下文中，您可以选择性地附加自定义编码器。

// Preventing double-encoding by using NullEncoder with the base cipher
$cipher = new AdvancedEncryptionStandardCipher('256-BIT-KEY-HERE', new NullEncoder());


// Initializing the encryption service with the configured cipher and property reader
$encryptionService = new ObjectEncryptionService($cipher, new RuntimeObjectPropertiesReader());

// Example of encrypting and decrypting user data
$user = new User();
$user->setSocialSecurityNumber('123-45-6789');

// Encrypt properties. The operation returns a string that is not binary-safe,
// and may require encoding to be safely transmitted or stored.
$encryptedUser = $encryptionService->encrypt($user);

// Decrypt properties
$decryptedUser = $encryptionService->decrypt($encryptedUser);

注意

除非另有说明，所有加密器都使用 Base64Encoder 作为默认编码器，以确保加密数据是二进制安全的，并且适合在不同系统之间传输或存储。

贡献

欢迎对SecureProps做出贡献。请确保您的代码遵守项目编码标准，并包括新功能或错误修复的测试。

许可

SecureProps是开源软件，根据MIT许可授权。