AutoTLS Integration Action Plan for py-libp2p

[Fatumayattani]

AutoTLS Integration Action Plan for py-libp2p

Related Issue: #555

Hi everyone

This is a proposed action plan for adding AutoTLS support to py-libp2p to make TLS configuration seamless, automated, and aligned with what’s already available in go-libp2p and js-libp2p.

The goal is to introduce a modular AutoTLS layer that supports both ephemeral self-signed certificates (for quick dev and test setups) and ACME/Let’s Encrypt certificates for production environments.

---

Proposed File & Module Structure

libp2p/security/tls/
├── autotls/
│   ├── __init__.py
│   ├── manager.py         
│   ├── acme_client.py     
│   ├── cache.py           
│   ├── config.py          
│   └── utils.py           
├── transport.py          

---

Core Functional Components

1. AutoTLS Manager (manager.py)

• Handles ephemeral self-signed cert generation.
• Tracks expiry and triggers renewal.
• Exposes a simple interface to the TLS transport.
• Keeps everything developer-friendly by default.

2. ACME Client (acme_client.py)

• Provides optional integration with Let’s Encrypt.
• Issues and renews certs automatically.
• Uses staging by default to avoid rate limits.
• ACME interaction is fully decoupled from the core transport.

3. Cache Layer (cache.py)

• Stores certs on disk or in memory.
• Handles cache expiry and renewal triggers.
• Prevents unnecessary regeneration.

4. Configuration (config.py)

• Centralizes all environment variables and defaults.

• Allows users to opt in to ACME or stay with ephemeral mode.

• Supports flags like:

  enable_autotls = True
  use_acme = False
  acme_directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"

5. Transport Integration (transport.py)

• Checks configuration flags.
• Initializes AutoTLS manager on startup.
• Injects the generated certs into the existing TLS handshake flow.
• Ensures no breaking change to manual TLS configuration.

---

Testing Strategy

tests/security/autotls/
├── test_autotls_manager.py
├── test_autotls_acme.py
└── test_autotls_integration.py

• Unit Tests

  • Ephemeral cert generation
  • Renewal flow
  • Cache read/write
  • ACME mock issuance and error handling

• Integration Tests

  • Launch a minimal libp2p host with AutoTLS enabled.
  • Test basic handshake and connection.
  • Verify cert renewal triggers correctly.

• Edge Cases

  • Expired cert handling
  • Invalid ACME configuration
  • Cache corruption or missing certs

---

Summary of the Plan

• Introduce AutoTLS inside the existing libp2p/security/tls/ layer.
• Keep ephemeral mode as the default for simplicity.
• Make ACME opt-in for production usage.
• Modular design ensures minimal changes to existing TLS code.
• Cover the full lifecycle (issue → cache → renew → integrate).
• Include robust testing and error handling from day one.

This plan is designed to deliver a complete and well-structured AutoTLS feature set while staying fully aligned with libp2p’s security design principles and the approaches used in other language implementations.

cc @seetadev @acul71 @pacrob @yashksaini-coder (collaborator)