keboola / object-encryptor
JSON object encryption library
Requires
- php: >=8.2
- ext-json: *
- ext-zlib: *
- aws/aws-sdk-php: ^3.209
- defuse/php-encryption: ^2.3
- google/cloud-kms: ^1.20
- keboola/azure-key-vault-client: ^3.0
- keboola/common-exceptions: ^1.2
- vkartaviy/retry: ^0.2
Requires (Dev)
- infection/infection: ^0.26
- keboola/coding-standard: ^15.0
- phpstan/phpstan: ^1.8
- phpstan/phpstan-phpunit: ^1.0
- phpunit/phpunit: ^9.5
- sempro/phpunit-pretty-print: ^1.4
- symfony/dotenv: ^5.4|^6.0
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 or Google Cloud KMS.
Requirements
The library supports PHP 8.1+.
Usage
Entry point to the library is the ObjectEncryptorFactory
class which creates instances of ObjectEncryptor
class which
has encryptGeneric
, encryptForComponent
, encryptForProject
, encryptForConfiguration
, encryptForProjectWide
encryptForBranchType
, encryptForBranchTypeConfiguration
, encryptForProjectWideBranchType
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
and getGcpEncryptor
to get cloud specific object encryptors.
Wrappers
Depending on the provided keys and parameters, the following wrappers will be available:
GenericKMSWrapper
- AWS KMS wrapper forKBC::Secure::
ciphers, requireskmsKeyId
andkmsRegion
. Also, the runner must have AWS credentials available (AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
)ComponentKMSWrapper
- AWS KMS wrapper forKBC::ComponentSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
andcomponentId
ProjectKMSWrapper
- AWS KMS wrapper forKBC::ProjectSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,componentId
andprojectId
.ConfigurationKMSWrapper
- AWS KMS wrapper forKBC::ConfigSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,componentId
,projectId
andconfigurationId
.ProjectWideKMSWrapper
- AWS KMS wrapperKBC::ProjectWideSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
, andprojectId
.BranchTypeProjectKMSWrapper
- AWS KMS wrapperKBC::BranchTypeSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,componentId
, projectIdand
branchType`.BranchTypeConfigurationKMSWrapper
- AWS KMS wrapperKBC::BranchTypeConfigSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,componentId
,projectId
,configurationId
andbranchType
.BranchTypeProjectWideKMSWrapper
- AWS KMS wrapperKBC::ProjectWideBranchTypeSecure::
ciphers, requireskmsKeyId
,kmsRegion
,stackId
,projectId
andbranchType
.GenericAKVWrapper
- Azure Key Vault wrapper forKBC::SecureKV::
ciphers, requiresakvUrl
. Also, the runner must have AWS credentials available (AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
)ComponentAKVWrapper
- Azure Key Vault wrapper forKBC::ComponentSecureKV::
ciphers, requiresakvUrl
,stackId
andcomponentId
ProjectAKVWrapper
- Azure Key Vault wrapper forKBC::ProjectSecureKV::
ciphers, requiresakvUrl
,stackId
,componentId
andprojectId
.ConfigurationAKVWrapper
- Azure Key Vault wrapper forKBC::ConfigSecureKV::
ciphers, requiresakvUrl
,stackId
,componentId
,projectId
andconfigurationId
.ProjectWideAKVWrapper
- Azure Key Vault wrapperKBC::ProjectWideSecureKV::
ciphers, requiresakvUrl
,stackId
, andprojectId
.BranchTypeProjectAKVWrapper
- Azure Key Vault wrapperKBC::BranchTypeSecureKV::
ciphers, requiresakvUrl
,stackId
,componentId
, projectIdand
branchType`.BranchTypeConfigurationAKVWrapper
- Azure Key Vault wrapperKBC::BranchTypeConfigSecureKV::
ciphers, requiresakvUrl
,stackId
,componentId
,projectId
,configurationId
andbranchType
.BranchTypeProjectWideAKVWrapper
- Azure Key Vault wrapperKBC::ProjectWideBranchTypeSecureKV::
ciphers, requiresakvUrl
,stackId
,projectId
andbranchType
.GenericGKMSWrapper
- Google KMS wrapper forKBC::SecureGKMS::
ciphers, requiresgkmsKeyId
. Also, the runner must have AWS credentials available (AWS_ACCESS_KEY_ID
,AWS_SECRET_ACCESS_KEY
)ComponentGKMSWrapper
- Google KMS wrapper forKBC::ComponentSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
andcomponentId
ProjectGKMSWrapper
- Google KMS wrapper forKBC::ProjectSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
,componentId
andprojectId
.ConfigurationGKMSWrapper
- Google KMS wrapper forKBC::ConfigSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
,componentId
,projectId
andconfigurationId
.ProjectWideGKMSWrapper
- Google KMS wrapperKBC::ProjectWideSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
, andprojectId
.BranchTypeProjectGKMSWrapper
- Google KMS wrapperKBC::BranchTypeSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
,componentId
, projectIdand
branchType`.BranchTypeConfigurationGKMSWrapper
- Google KMS wrapperKBC::BranchTypeConfigSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
,componentId
,projectId
,configurationId
andbranchType
.BranchTypeProjectWideGKMSWrapper
- Google KMS wrapperKBC::ProjectWideBranchTypeSecureGKMS::
ciphers, requiresgkmsKeyId
,stackId
,projectId
andbranchType
.
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 access to cloud providers
- installed Azure CLI
az
(and runaz login
) - installed AWS CLI
aws
(and runaws configure --profile YOUR_AWS_PROFILE_NAME
) - installed GCP CLI
gcloud
(and rungcloud auth login
orgcloud auth application-default login
)
- installed Azure CLI
- 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
export NAME_PREFIX= # your name/nickname to make your resource unique & recognizable export AWS_PROFILE= # your AWS profile name e.g. Keboola-Dev-Platform-Services-AWSAdministratorAccess cat <<EOF > ./provisioning/local/terraform.tfvars name_prefix = "${NAME_PREFIX}" EOF terraform -chdir=./provisioning/local init -backend-config="key=object-encryptor/${NAME_PREFIX}.tfstate" terraform -chdir=./provisioning/local apply ./provisioning/local/update-env.sh aws # or azure or gcp docker-compose run --rm tests
License
MIT licensed, see LICENSE file.