Connect by JBRH Open Connect

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 What this means
Audience
both, developer
Last verified
Product version
6.3.2

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, argon2-cffi.readthedocs.io

Where Connect uses it#

Place in ConnectWhat it does there
backend/app/crypto.pyEncryption and decryption of stored secrets (Fernet)
backend/app/email_delivery_webhooks.pyVerifying signed delivery notifications
backend/app/saas_sso.pySingle sign-on signatures and certificates
backend/app/app_auth.py, account_auth.pyArgon2 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).
  • 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).

Licence, cost and versions#

QuestionAnswer
Licencecryptography: Apache-2.0 or BSD-3-Clause. argon2-cffi: MIT
CostNone
Versioncryptography>=42; argon2-cffi within 25.x
Compatibilitycryptography 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#

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.