Certificate generation utilities#

The certificate generation utilities provide a convenient way to generate self-signed certificates suitable for testing gRPC applications with mutual TLS authentication. These utilities are particularly useful for pytest fixtures and local development environments.

Important

These certificates are for testing purposes only. Do not use them in production environments. For production deployments, always use certificates from a trusted Certificate Authority. For guidance on how to generate certificates for local development, see the Securing gRPC connections documentation.

Note

By default, generated certificates are valid for only 24 hours. This short validity period is intentional for testing environments to encourage certificate regeneration and avoid stale credentials. You can customize this using the validity_days parameter if needed.

Installation#

Install Ansys Common Tools with the other optional dependency group to enable certificate generation:

pip install ansys-tools-common[other]

uv sync --extra other

Quick start#

The simplest way to generate certificates is using the generate_test_certificates() function:

from ansys.tools.common.utils import generate_test_certificates
from pathlib import Path

# Generate certificates for localhost
files = generate_test_certificates(output_dir=Path("certs"))

# The following files are created:
# - ca.key, ca.crt (Certificate Authority)
# - server.key, server.crt (Server certificate)
# - client.key, client.crt (Client certificate)

Pytest integration#

The utilities are designed to integrate seamlessly with pytest fixtures, making it easy to set up secure testing environments:

Basic fixture#

import pytest
from pathlib import Path
from ansys.tools.common.utils import generate_test_certificates


@pytest.fixture(scope="session")
def tls_certificates(tmp_path_factory):
    """Generate TLS certificates for testing."""
    cert_dir = tmp_path_factory.mktemp("certs")
    generate_test_certificates(output_dir=cert_dir)

    return {
        "ca_cert": cert_dir / "ca.crt",
        "ca_key": cert_dir / "ca.key",
        "server_cert": cert_dir / "server.crt",
        "server_key": cert_dir / "server.key",
        "client_cert": cert_dir / "client.crt",
        "client_key": cert_dir / "client.key",
    }


def test_grpc_with_mtls(tls_certificates):
    """Test gRPC server with mutual TLS."""
    # Use the certificates in your test
    server_cert = tls_certificates["server_cert"]
    server_key = tls_certificates["server_key"]
    ca_cert = tls_certificates["ca_cert"]

    # Set up your gRPC server with these certificates
    # ...

Advanced usage#

HPC deployment with multiple servers#

For HPC environments where you need certificates for multiple nodes:

from ansys.tools.common.utils import generate_test_certificates
from pathlib import Path

files = generate_test_certificates(
    servers=[
        "node01,192.0.2.1",  # Primary hostname + IP SAN
        "node02,192.0.2.2",
        "node03,192.0.2.3",
    ],
    output_dir=Path("hpc_certs"),
)

# This creates:
# - ca.key, ca.crt
# - node01.key, node01.crt (with SAN: 192.0.2.1)
# - node02.key, node02.crt (with SAN: 192.0.2.2)
# - node03.key, node03.crt (with SAN: 192.0.2.3)
# - client.key, client.crt

HPC fixture example#

import pytest
from pathlib import Path
from ansys.tools.common.utils import generate_test_certificates


@pytest.fixture(scope="session")
def hpc_tls_certificates(tmp_path_factory):
    """Generate TLS certificates for HPC deployment."""
    cert_dir = tmp_path_factory.mktemp("hpc_certs")
    server_specs = [
        "node01,192.0.2.1",
        "node02,192.0.2.2",
        "node03,192.0.2.3",
    ]

    generate_test_certificates(servers=server_specs, output_dir=cert_dir)

    result = {
        "ca_cert": cert_dir / "ca.crt",
        "ca_key": cert_dir / "ca.key",
        "client_cert": cert_dir / "client.crt",
        "client_key": cert_dir / "client.key",
        "cert_dir": cert_dir,
        "servers": {},
    }

    # Add server-specific certificates
    for spec in server_specs:
        server_name = spec.split(",")[0]
        result["servers"][server_name] = {
            "cert": cert_dir / f"{server_name}.crt",
            "key": cert_dir / f"{server_name}.key",
        }

    return result

Custom validity period#

By default, certificates are valid for 24 hours (1 day). This short validity period is intentional for testing to ensure certificates are regenerated frequently. You can customize this if needed:

from ansys.tools.common.utils import generate_test_certificates
from pathlib import Path

# Generate certificates valid for 3 days
files = generate_test_certificates(output_dir=Path("certs"), validity_days=3)

Using the CertificateGenerator class#

For more control over certificate generation, use the CertificateGenerator class directly:

from ansys.tools.common.utils import CertificateGenerator
from pathlib import Path

# Initialize generator with custom parameters
generator = CertificateGenerator(key_size=4096, validity_days=3)

# Generate CA certificate
ca_key, ca_cert = generator.create_ca_certificate("My Test CA")

# Generate server certificate with SANs
server_key, server_cert = generator.create_server_certificate(
    ca_cert, ca_key, "myserver.local", san_names=["192.168.1.100", "myserver"]
)

# Generate client certificate
client_key, client_cert = generator.create_client_certificate(
    ca_cert, ca_key, "Test Client"
)

# Save certificates
output_dir = Path("custom_certs")
output_dir.mkdir(exist_ok=True)

generator.save_private_key(server_key, output_dir / "server.key")
generator.save_certificate(server_cert, output_dir / "server.crt")
# ... save other certificates

Security considerations#

The generated certificates have the following characteristics:

  • Self-signed: Not validated by any certificate authority

  • Predictable parameters: Generated with standard key sizes and algorithms

  • No revocation support: No certificate revocation lists (CRLs) or OCSP

  • Testing only: Intended only for local development and testing

For production deployments:

  • Use certificates from a trusted Certificate Authority (CA)

  • Implement proper certificate rotation and expiration policies

  • Use hardware security modules (HSMs) for key management when appropriate

  • Follow your organization’s security policies and compliance requirements

Use cases#

Common use cases for these certificate utilities include:

  • Unit and integration tests: Set up secure gRPC connections in test suites

  • Local development: Test TLS-enabled features without external dependencies

  • CI/CD pipelines: Generate ephemeral certificates for test environments

  • HPC testing: Simulate multi-node secure communication

  • Documentation examples: Provide working security examples without sharing real credentials