# Cryptography and password hashing

Two libraries carry Connect's cryptography. `cryptography` encrypts the credentials a business stores in Connect, such as provider keys and tokens, and verifies signed messages from providers. `argon2-cffi` hashes passwords with Argon2, so a password is checked without ever being stored. Webhook HMACs use Python's standard `hmac` module.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/python-cryptography/

## What it is

`cryptography` is maintained by the Python Cryptographic Authority. It offers high-level recipes, such as Fernet authenticated encryption, and low-level primitives (`hazmat`) built on OpenSSL.

`argon2-cffi` binds the reference Argon2 implementation. Argon2 won the Password Hashing Competition in 2015 and is specified in RFC 9106. It is deliberately slow and memory-hard, which makes guessing passwords from a stolen hash expensive.

**Category** — Cryptography libraries
**Versions in Connect** — `cryptography>=42`; `argon2-cffi>=25.1,<26`
**Recipes used** — Fernet; elliptic-curve and RSA signature verification; X.509
**Official sites** — [cryptography.io](https://cryptography.io/), [argon2-cffi.readthedocs.io](https://argon2-cffi.readthedocs.io/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `backend/app/crypto.py` | Encryption and decryption of stored secrets (Fernet) |
| `backend/app/email_delivery_webhooks.py` | Verifying signed delivery notifications |
| `backend/app/saas_sso.py` | Single sign-on signatures and certificates |
| `backend/app/app_auth.py`, `account_auth.py` | Argon2 password hashes for passwords and one-time codes |

## How it connects

1. A business saves a provider key in settings
2. `crypto.py` encrypts it with the host's key before it is written
3. PostgreSQL stores only ciphertext
4. At use, it is decrypted in memory for the one request
5. Inbound webhooks are verified (HMAC or signature) before their content is trusted

## Benefits and limits

What it gives Connect:

- Fernet is authenticated: tampered ciphertext fails to decrypt rather than decrypting to garbage.
- Argon2 parameters can be raised over time, and the stored hash records its own parameters.
- Signature checks use constant-time comparison (`hmac.compare_digest`).

Where it stops, and what Connect does about it:

- Encryption at rest is only as strong as the key's custody. The key lives in the host environment, not the database ([encryption at rest](/docs/technology/encryption-at-rest/)).
- Rotating the encryption key means re-encrypting stored values. `crypto.py` is a wide-radius file and runs the whole regression set when it changes.
- Argon2 costs CPU per sign-in by design. Sign-in endpoints are rate limited.

## Security and privacy

- No plaintext secret is written to the database or the logs.
- Passwords and codes are stored as hashes, and a code is limited per network and per address.
- Provider webhooks without a valid signature are refused. A nonce index stops replay ([webhook signatures](/docs/technology/webhook-signature/)).

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | cryptography: Apache-2.0 or BSD-3-Clause. argon2-cffi: MIT |
| Cost | None |
| Version | `cryptography>=42`; `argon2-cffi` within 25.x |
| Compatibility | cryptography ships wheels with its own OpenSSL for Linux x86-64 |

## Troubleshooting

**`InvalidToken` when reading a stored credential** — The encryption key on the host is not the key the value was written with. Restore the right key; do not re-save over the value.
**Webhook refused as unsigned** — The provider's signing secret in settings does not match, or a proxy changed the body. Signatures cover the raw bytes.
**Sign-in feels slow** — Expected within reason: Argon2 is meant to cost time.

## Official references

- [cryptography documentation](https://cryptography.io/en/latest/)
- [Fernet specification](https://github.com/fernet/spec/blob/master/Spec.md)
- [RFC 9106: Argon2](https://www.rfc-editor.org/rfc/rfc9106)
- [argon2-cffi documentation](https://argon2-cffi.readthedocs.io/)

## Questions

### Can Connect's staff read my stored API keys?

They are encrypted at rest and decrypted only in memory for the request that uses them. Screens show that a key is saved, never the key itself.

### Why Argon2 and not bcrypt?

Argon2 is memory-hard as well as slow, which raises the cost of guessing on GPUs, and it is the current recommendation of RFC 9106 and OWASP.

## Related

- [Encryption at rest](https://connectbyjbrh.com/docs/technology/encryption-at-rest/)
- [Secret management](https://connectbyjbrh.com/docs/technology/secret-management/)
- [Provider webhook signatures](https://connectbyjbrh.com/docs/technology/webhook-signature/)
- [Credential rotation](https://connectbyjbrh.com/docs/technology/credential-rotation/)

## What this page is based on

- `backend/app/crypto.py`
- `backend/app/app_auth.py`
- `backend/app/account_auth.py`
- `requirements.txt`
- https://www.rfc-editor.org/rfc/rfc9106
