django-ecp-auth

Two-factor authentication for Django using ECDSA digital signatures. Plugs into any existing project via two mixins — no replacement of existing auth logic required.

pip install django-ecp-signer

What is this?

django-ecp-auth adds a digital signature layer on top of standard Django username/password authentication.

Upon registration, the server generates an ECDSA key pair. The user downloads the private key as an encrypted .pem file (protected by a passphrase they choose) and the public certificate as a separate .pem file. On every login, JavaScript reads the private key file, decrypts it with the passphrase, signs a one-time server challenge, and submits the signature. The server verifies the signature against the stored public certificate.

The private key never leaves the user's machine. The server stores only the public certificate.

Key concepts

private_key.pem — downloaded once after registration. Encrypted with a passphrase (AES-256-CBC). Used client-side to sign the challenge. Never sent to the server.

certificate.pem — the public X.509 certificate. Stored in the database server-side. Also given to the user so they can re-upload it later (e.g. to a new server instance) without generating a new key pair.

Nonce — a random string generated by the server for each login attempt. Signed by the client, consumed atomically on the server (SELECT FOR UPDATE) after first use to prevent replay attacks.

Registration flow

1. User submits the registration form — username, password, and key_password (passphrase for the private key).
2. CreateView creates the User object as usual.
3. ECPGenerateMixin runs automatically:
   • Generates an ECDSA P-256 key pair.
   • Builds a self-signed X.509 certificate valid for 365 days.
   • Saves only the public certificate to the database (ECPCertificate).
   • Encrypts the private key with key_password and stores both PEM strings in the session.
4. Frontend offers two separate downloads:
   • GET /ecp/keys/?file=private_key → private_key.pem (encrypted, keep secret)
   • GET /ecp/keys/?file=certificate → certificate.pem (public, safe to share)

Each file is cleared from the session individually after it is served.

Login flow

1. The login page fetches a nonce: GET /ecp/challenge/.
2. User fills in username and password, selects their private_key.pem file, and enters their key_password.
3. JavaScript reads the file, decrypts the private key locally, signs the nonce (ECDSA SHA-256), then discards the key from memory. The key file and passphrase are never sent to the server.
4. The form submits username, password, nonce_id, and signature.
5. The server runs two checks in sequence:
   • Password check — standard Django authenticate(username, password).
   • Signature check — fetches the certificate from the database, atomically consumes the nonce, and verifies the ECDSA signature.
6. On success: session is opened, user is redirected.

Re-registering a certificate (BYOK)

A user can upload their saved certificate.pem to replace the one stored on the server — useful when moving to a new server instance, after a database reset, or when bringing a self-generated key pair:

POST /ecp/certificate/
Content-Type: multipart/form-data

certificate=<certificate.pem>

The server validates that the certificate is not expired and that its Common Name (CN) matches the username, then stores it. The user's existing private_key.pem continues to work for signing.

What is stored where

Security

Setup

1. settings.py

INSTALLED_APPS = [
    ...
    'ecp_auth',
]

AUTHENTICATION_BACKENDS = [
    'ecp_auth.backends.ECPAuthenticationBackend',
]

# Optional: nonce lifetime (default 5 minutes)
from datetime import timedelta
NONCE_LIFETIME = timedelta(minutes=5)

2. urls.py

path("ecp/", include("ecp_auth.urls")),

3. views.py

from ecp_auth.mixins import ECPGenerateMixin, ECPLoginMixin

class RegisterView(ECPGenerateMixin, CreateView):
    ...

class LoginView(ECPLoginMixin, FormView):
    ...

ECPGenerateMixin reads the user from form.instance and must be used with CreateView. The registration form must include a key_password field — this passphrase encrypts the private key.

ECPLoginMixin expects the login form to have:

4. Migrate

python manage.py migrate

Endpoints

Challenge response

{ "nonce": "3f8a1c...", "nonce_id": 42 }

Keys response (JSON)

{
  "private_key": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...",
  "certificate": "-----BEGIN CERTIFICATE-----\n..."
}

File download

Returns application/x-pem-file with Content-Disposition: attachment. Each file is cleared from the session only when it is served.

Certificate upload

Returns {"status": "ok"} on success, or {"error": "..."} with status 400 on failure.

Maintenance

Remove stale nonces periodically to prevent table bloat:

python manage.py cleanup_nonces

Deletes all nonces that are used or older than NONCE_LIFETIME. Safe to run via cron or Celery beat.

Exceptions

All exceptions inherit from ECPAuthError.

ECPAuthError
├── InvalidSignatureError
├── CertificateExpiredError
├── InvalidCertificateError
├── NonceExpiredError
└── NonceNotFoundError

Requirements

• Python >= 3.12
• Django >= 4.2
• cryptography >= 42.0

Running tests

pip install pytest pytest-django
pytest tests/ -v