Metadata-Version: 2.4
Name: pxa-security
Version: 2.0.0
Summary: Credential encryption utilities for configuration files.
Author-email: Daniel Lee <rootuser.kr@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/asulikeit/pxa-security
Project-URL: Repository, https://github.com/asulikeit/pxa-security
Project-URL: Issues, https://github.com/asulikeit/pxa-security/issues
Keywords: encryption,aes,aes-gcm,password,kdf,scrypt
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# pxa-security

Credential encryption utilities for configuration files.

```bash
pip install pxa-security
```

The distribution name is `pxa-security`; the import name is `pxa_security`.

## Usage

Use a secret master key that is supplied separately from the configuration
file, normally through an environment variable or a secret manager. Tokens
use scrypt with a per-token random salt and AES-GCM authenticated
encryption.

```python
import os

from pxa_security import encrypt_credential, decrypt_credential

master_key = os.environ["PXA_CREDENTIAL_MASTER_KEY"]

# The token is safe to store in a config file; the master key is not.
token = encrypt_credential(master_key, "s3cret!")

# Decrypt with the separately supplied master key.
password = decrypt_credential(master_key, token)
assert password == "s3cret!"
```

A wrong master key, damaged token, or modified token raises `ValueError`:

```python
decrypt_credential("wrong-master-key", token)  # ValueError
```

Use at least 32 random bytes for the master key and never write it beside the
encrypted token. A username, application name, or other public identifier is
not a master key. One suitable value can be generated with
`secrets.token_urlsafe(32)` and then provisioned through your deployment's
secret store. A shorter master key is accepted — every token carries a
random scrypt salt, so it still encrypts and decrypts correctly — but it
weakens the encryption accordingly.

## API summary

| Function | Description |
| --- | --- |
| `encrypt_credential(master_key: str \| bytes, credential: str) -> str` | Encrypts a credential with a separately managed secret and returns an ASCII token. |
| `decrypt_credential(master_key: str \| bytes, encrypted_credential: str \| bytes) -> str` | Authenticates and decrypts a token produced by `encrypt_credential`. |

## Security notes

AES-GCM ensures ciphertext modification and wrong keys are detected. scrypt
makes offline guessing more expensive, but it cannot compensate for a weak
or exposed master key. Keep the master key out of source control and
configuration files.

## License

Apache License 2.0 — see [LICENSE](LICENSE).
