Package: python-jose-aws-kms-extension
python-jose_aws-kms-extensionThis library is anextension ofpython-joselibrary.
It usesmonkey-patchingto extend the capabilities ofpython-jose.
It provides JWE based encrypters/decrypters and JWS based signers/verifiers for doing operations with cryptographic
keys stored in AWS KMS. This library requirespython>=3.8,<4andpython-jose=3.3.0.InstallationYou can install the library from PyPI. It's available under the namepython-jose_aws-kms-extension.
Following is an installation example usingpip3command.pip3 install python-jose_aws-kms-extensionUsageIn order to use this library you'll need to import its top level package,
before importing anypython-josemodules/packages. This ensures that monkey-patching implemented in this library
works as expected.importjose_aws_kms_extensionfromjoseimport<something>After importing this library's top level package, you can use all existingpython-josefeatures,
as you'll do in absense of this library. This library adds AWS KMS support on top of those features, in a
transparent ways. I.e., you can use your AWS KMS keys for various encryption and signing operations,
using the regularpython-josefunctions.
You can use AWS KMS specified algorithm names for these operations.
This library supports all algorithms supported by AWS KMS.
List of supported algorithms can also be viewed at thejose_aws_kms_extension.constants.Algorithmsclass.Following are the supportedpython-josefunctions:jose.jwe.encrypt()jose.jwe.decrypt()jose.jws.sign()jose.jws.verify()This library usesboto3for all it's communication with AWS KMS.
You can provide a KMS key in one of following two possible formats:Key string: This can be a string containing a KMS key-id, key-id ARN, key-alias or key-alias ARN.Key object: This can be an object of one of following classes.
Using a key object allows you to customize theboto3KMS client.For encrypt/decrypt:jose_aws_kms_extension.backends.kms.symmetric.encryption.BotoKMSSymmetricEncryptionKeyFor sign/verify:jose_aws_kms_extension.backends.kms.asymmetric.signing.BotoKMSAsymmetricSigningKeyNext sections cover few examples of encryption and signing operations supported by this library.Encrypt/DecryptEncrypt/Decrypt with a String Key>>>importjose_aws_kms_extension>>>fromjoseimportjwe>>>jwe.encrypt(plaintext='Hello, World!',key='<your KMS key string>',algorithm='SYMMETRIC_DEFAULT',encryption='A128GCM',kid='<your KMS key string>')b'<compact serialized JWE token>'>>>jwe.decrypt(jwe_str=b'<compact serialized JWE token>',key='<your KMS key string>').decode('utf-8')'Hello, World!'Encrypt/Decrypt with a Key Object>>>importjose_aws_kms_extension>>>fromjoseimportjwe>>>fromjose_aws_kms_extension.backends.kms.symmetric.encryptionimportBotoKMSSymmetricEncryptionKey>>>importboto3>>>frombotocore.configimportConfig>>>kms_client=boto3.client('kms',config=Config(<yourAWSconfig>))>>>kms_encryption_key=BotoKmsSymmetricEncryptionKey(key='<your KMS key string>',algorithm='SYMMETRIC_DEFAULT',kms_client=kms_client)>>>jwe.encrypt(plaintext='Hello, World!',key=kms_encryption_key,algorithm='SYMMETRIC_DEFAULT',encryption='A128GCM',kid='<your KMS key string>')b'<compact serialized JWE token>'>>>jwe.decrypt(jwe_str=b'<compact serialized JWE token>',key=kms_encryption_key).decode('utf-8')'Hello, World!'Encrypt with Addition HeadersJWSandJWE,
both specs have the provision of custom (i.e. user-defined) headers.python-josesupports passing custom headers
in theheadersparameter injose.jws.sign()method. But the same is not supported injose.jwe.encrypt()method.
We have opened theissue 321to add this support.
But until the issue is resolved, we have added this capability via this library.Following example shows how custom headers can be passed injose.jwe.ecrypt()function.>>>importjose_aws_kms_extension>>>fromjoseimportjwe>>>jwe.encrypt(plaintext='Hello, World!',key='<your KMS key string>',algorithm='SYMMETRIC_DEFAULT',encryption='A128GCM',kid='<your KMS key string>',additional_headers={'addition-header1':'val1','additional-header2':'val2'})b'<compact serialized JWE token>'Sign/VerifySign/Verify with a String Key>>>importjose_aws_kms_extension>>>fromjoseimportjws>>>jws.sign(payload='Goodbye, World!'.encode('utf-8'),key='<your KMS key string>',headers={'kid':'<your KMS key string>',<otherheaders>},algorithm='RSASSA_PSS_SHA_512')'<compact serialized JWS token>'>>>jws.verify(token='<compact serialized JWS token>',key='<your KMS key string>',algorithms='RSASSA_PSS_SHA_512').decode('utf-8')'Goodbye, World!'Sign/Verify with a Key Object>>>importjose_aws_kms_extension>>>fromjoseimportjws>>>fromjose_aws_kms_extension.backends.kms.asymmetric.signingimportBotoKMSAsymmetricSigningKey>>>importboto3>>>frombotocore.configimportConfig>>>kms_client=boto3.client('kms',config=Config(<yourAWSconfig>))>>>kms_signing_key=BotoKMSAsymmetricSigningKey(key='<your KMS key string>',algorithm='RSASSA_PSS_SHA_512',kms_client=kms_client)>>>jws.sign(payload='Goodbye, World!'.encode('utf-8'),key=kms_signing_key,headers={'kid':'<your KMS key string>',<otherheaders>},algorithm='RSASSA_PSS_SHA_512')'<compact serialized JWS token>'>>>jws.verify(token='<compact serialized JWS token>',key=kms_signing_key,algorithms='RSASSA_PSS_SHA_512').decode('utf-8')'Goodbye, World!'Building the ProjectThis project usespyproject.toml,PoetryandPoe the Poetfor build.
You'll need to install Poetry in your system before you can build the project.PoetryInstallation GuideFirst Time Dependency InstallationAfter installingPoetryyou'll need to execute the following commands for the first time depdency installation.poetry installThis command will install all the dependencies defined inpyproject.tomlfile, includingPoe the Poet.
After running this command for the first time, you won't need to run this command again for the successive builds.
For all future builds, you can simply run the command covered in the next section.Build CommandUse following command to do a release build (i.e., a full build including unit-test execution).poetry run poe releaseThis will execute thereleasetask, which is a sequence of multiple sub-tasks. To view all sub-tasks and other
available tasks, see the[tool.poe.tasks]sections inpyproject.tomlfile.You'll needpython3.8command to be available in your CIL'sPATH, for the release command to be successful.
You can either use your system's Python,pyenv,
or whichever way you prefer for installing Python.Note: If you are using Homebrew on MacOS for installing/upgrading Python, then you may face following issue:https://github.com/python-poetry/install.python-poetry.org/issues/71Building with Other Python VersionsIf you want to build the project with a Python version other than 3.8, you can use following commandspoetry env use <your-python-version>
poetry run poe env-releaseFor more details on using your Python environment for the build,
seePoerty'sdocumentation onManaging environments.