TLS y certificados¶
wsbuilder.pki crea una autoridad certificadora, emite certificados y los rota.
Necesita el extra opcional:
python -m pip install "wsbuilder[tls]"
Por que existe este modulo¶
ssl.SSLContext.load_cert_chain() solo acepta rutas de archivo: OpenSSL no
lee un certificado ni una clave desde memoria. Un certificado guardado en una
fila de base de datos, en un gestor de secretos o construido al arrancar tiene
que pasar por el disco antes de poder cifrar nada.
Este modulo reduce esa ventana al minimo. El PEM se escribe en un directorio
temporal privado (0700) con permisos 0600, se entrega a OpenSSL y se borra
acto seguido: el SSLContext ya tiene su propia copia.
Sobre el borrado
Los bytes se sobrescriben antes de desenlazar el archivo, lo que impide leerlo despues por esa ruta. No es una garantia de destruccion. Un sistema de archivos con copy-on-write, un journal o el nivelado de desgaste de un SSD pueden conservar los bloques antiguos. Trata una maquina que ejecuta esto como una maquina que ha visto la clave.
Arranque rapido¶
from wsbuilder import App
app = App()
manager = app.enable_tls(common_name="localhost")
app.run("127.0.0.1", 8443, ssl_context=manager)
Sin argumentos crea una CA local desechable, suficiente para desarrollo.
Crear la CA y emitir¶
from wsbuilder import CertificateAuthority
ca = CertificateAuthority.create("Mi CA", organization="Acme", valid_days=3650)
leaf = ca.issue(
"api.example.test",
dns_names=["api.example.test", "alt.example.test"],
ip_addresses=["127.0.0.1"],
valid_days=30,
)
Ambas mitades son PEM plano, asi que guardarlas es escribir dos columnas:
ca.certificate_pem # bytes
ca.private_key_pem # bytes
ca.private_key_pem_encrypted("passphrase") # cifrada, si va a viajar
CertificateAuthority.load(cert_pem, key_pem) # recuperar
CertificateAuthority.load(cert_pem, key_pem, password=".") # si estaba cifrada
Si no indicas dns_names, el nombre comun se copia al SAN: los verificadores
dejaron de mirar el common name, asi que un certificado sin SAN no coincide con
nada. Una hoja nunca se emite mas alla de la caducidad de su CA.
Estatico o rotativo¶
CertificateManager guarda el material en uso. El modo lo decide rotate:
| Modo | Cuando reemplaza |
|---|---|
estatico (rotate=False) |
solo cuando el certificado ya caduco |
rotativo (rotate=True) |
cuando faltan menos de renew_before_seconds |
De donde sale el material es independiente del modo. provider se consulta
primero; si devuelve algo con vida suficiente, se usa tal cual. Si no, el
manager emite uno nuevo y se lo pasa a on_rotate.
El caso completo: material en base de datos¶
Es la forma para la que esta pensado el modulo. El PEM vive en la base de datos, toca disco solo como archivo temporal, y la rotacion reescribe la fila.
import sqlite3
from wsbuilder import App, CertificateAuthority, CertificateManager, TLSMaterial
db = sqlite3.connect("tls.db", check_same_thread=False)
db.execute("CREATE TABLE IF NOT EXISTS tls (name TEXT PRIMARY KEY, cert BLOB, key BLOB, chain BLOB)")
def cargar():
row = db.execute("SELECT cert, key, chain FROM tls WHERE name = ?", ("localhost",)).fetchone()
return None if row is None else TLSMaterial(row[0], row[1], row[2])
def guardar(material):
db.execute(
"INSERT OR REPLACE INTO tls VALUES (?, ?, ?, ?)",
("localhost", material.certificate_pem, material.private_key_pem, material.chain_pem),
)
db.commit()
ca = CertificateAuthority.create("Mi CA")
manager = CertificateManager(
ca=ca,
common_name="localhost",
dns_names=["localhost"],
ip_addresses=["127.0.0.1"],
provider=cargar, # reutiliza lo guardado entre reinicios
on_rotate=guardar, # escribe cada certificado nuevo
rotate=True,
valid_days=1,
renew_before_seconds=3600,
)
app = App()
app.run("127.0.0.1", 8443, ssl_context=manager)
En el primer arranque no hay fila: el manager emite y guardar la crea. En el
siguiente reinicio cargar devuelve ese mismo certificado y no se emite
otro. Cuando quedan menos de 3600 segundos de vida, se emite uno nuevo y la fila
se reescribe.
El servidor pide el contexto por conexion, asi que una rotacion llega a las conexiones nuevas sin reiniciar el proceso.
Usar el material fuera del servidor¶
Para herramientas que solo aceptan rutas:
with manager.materialize() as files:
subprocess.run(["curl", "--cert", files.certificate, "--key", files.private_key, url])
Al salir del bloque los archivos se borran. Si olvidas cerrarlo, un finalizador los borra al recolectar el objeto y, en el peor caso, al terminar el proceso.
Autenticacion de cliente (mTLS)¶
manager = CertificateManager(
ca=ca,
common_name="localhost",
client_ca_pem=ca.certificate_pem,
require_client_cert=True,
)
Con require_client_cert=False el certificado de cliente se acepta pero no se
exige.
Observabilidad¶
Con app.enable_metrics() activo, el snapshot incluye un bloque tls:
{
"tls": {
"mode": "rotating",
"rotations": 3,
"certificate": {
"subject": "CN=localhost",
"not_valid_after": "2026-09-21T15:05:06+00:00",
"seconds_until_expiry": 82000.0,
"dns_names": ["localhost"]
}
}
}
Referencia¶
| Simbolo | Uso |
|---|---|
CertificateAuthority.create(...) |
crear una raiz autofirmada |
CertificateAuthority.load(cert, key, password=None) |
recuperar una CA guardada |
CertificateAuthority.issue(...) |
emitir una hoja firmada |
TLSMaterial |
certificado + clave + cadena, como PEM |
TLSMaterial.materialize() |
escribirlo a archivos temporales privados |
TLSMaterial.ssl_context(...) |
construir un SSLContext |
CertificateManager |
material en uso, estatico o rotativo |
install_tls(app, ...) / app.enable_tls(...) |
dejarlo en app.tls |