keboola / object-encryptor
JSON object encryption library
Requires
- php: >=7.4
- ext-json: *
- ext-zlib: *
- aws/aws-sdk-php: ^3.209
- defuse/php-encryption: ^2.3
- keboola/azure-key-vault-client: ^2.0|^3.0
- keboola/common-exceptions: ^1.2
- phpseclib/mcrypt_compat: ^1.0
- vkartaviy/retry: ^0.2.2
Requires (Dev)
- infection/infection: ^0.18.2
- keboola/coding-standard: ^13.0
- phpstan/phpstan: ^1.8
- phpstan/phpstan-phpunit: ^1.0.0
- phpunit/phpunit: ^9.5
- sempro/phpunit-pretty-print: ^1.4
- symfony/dotenv: ^5.4
README
Object Encryptor
Library provides interface for encrypting PHP arrays, stdclass objects and scalars. A cipher may contain additional metadata which limits the conditions under which it may be decrypted. The library uses the defuse/php-encryption encryption method with AWS KMS or Azure Key Vault managed keys.
Requirements
The library supports PHP 7.4+.
Usage
Entry point to the library is the ObjectEncryptorFactory
class which creates instances of ObjectEncryptor
class which
has encryptGeneric
, encryptForComponent
, encryptForProject
, encryptForConfiguration
and corresponding decryptXXX
methods. The actual encryption and decryption mechanisms are implemented using Crypto Wrappers.
Crypto wrappers implement different verification methods using cypher metadata.
Usage
Initialize the library using the factory class:
$encryptor = ObjectEncryptorFactory::getEncryptor(
new EncryptorOptions(
'my-stack',
$kmsKeyId,
$kmsRegion,
$akvUrl
)
);
$encryptor->encryptForComponent('secret', 'my-component');
Alternatively, you can use getAwsEncryptor
and getAzureEncryptor
to get cloud specific object encryptors.
Wrappers
Depending on the provided keys and parameters, the following wrappers will be available:
GenericKMSWrapper
- current AWS wrapper forKBC::Secure::
ciphers, requireskmsKeyId
andkmsRegion
. Also, the runner must have AWS credentials available (AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
)ComponentKMSWrapper
- current AWS wrapper forKBC::ComponentSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
andcomponentId
ProjectKMSWrapper
- current AWS wrapper forKBC::ProjectSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,componentId
andprojectId
.ConfigurationKMSWrapper
- current AWS wrapper forKBC::ConfigSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,componentId
,projectId
andconfigurationId
.GenericAKVWrapper
- current Azure wrapper forKBC::SecureKV::
ciphers, requiresakvUrl
. Also, the runner must have AWS credentials available (AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
)ComponentAKVWrapper
- current Azure wrapper forKBC::ComponentSecureKV::
ciphers, requiresakvUrl
,stackId
andcomponentId
ProjectAKVWrapper
- current Azure wrapper forKBC::ProjectSecureKV::
ciphers, requiresakvUrl
,stackId
,componentId
andprojectId
.ConfigurationAKVWrapper
- current Azure wrapper forKBC::ConfigSecureKV::
ciphers, requiresakvUrl
,stackId
,componentId
,projectId
andconfigurationId
.
During encryption, the wrapper has to be specified (each encryptXXX
method uses one). During decryption,
the wrapper is chosen automatically by the cipher prefix. This means that decryptForConfiguration
method is also
capable of decrypting ciphers created by encryptForComponent
or encryptForProject
ciphers.
If the wrapper is not available (key or parameters are not set or equal to those in the cipher),
the value cannot be deciphered and an exception is thrown.
Development
Prerequisites:
- configured
az
andaws
CLI tools (runaz login
andaws configure --profile keboola-dev-platform-services
) - installed
terraform
(https://www.terraform.io) andjq
(https://stedolan.github.io/jq) to setup local env - installed
docker
anddocker-compose
to run & develop the app
cat <<EOF > ./provisioning/local/terraform.tfvars
name_prefix = "name" # your name/nickname to make your resource unique & recognizable
EOF
terraform -chdir=./provisioning/local init
terraform -chdir=./provisioning/local apply
./provisioning/local/update-env.sh aws # or azure
docker-compose run --rm tests
License
MIT licensed, see LICENSE file.