18. TLS Implementation in the ArmoniK Core

18.1. Overview

Transport Layer Security (TLS) is a cryptographic protocol designed to provide secure communication over a computer network. In ArmoniK, TLS is implemented to secure communications between various services such as RabbitMQ, MongoDB, Redis … This ensures that data transmitted between these services is encrypted and authenticated, protecting it from eavesdropping and tampering.

18.2. TLS Certificate Generation

TLS certificates are generated and managed using Terraform, which automates the creation of these certificates. The process involves creating a private key, a self-signed CA certificate, a certificate signing request (CSR), and a locally signed certificate. These certificates are then stored as local files and mounted into the respective service containers.

  • Private Key: A private key is generated using the RSA algorithm with 4096 bits.

  • Self-Signed CA Certificate: This certificate is used to sign other certificates, establishing a chain of trust.

  • Certificate Signing Request (CSR): A CSR is created for each service, specifying details such as the organization and common name.

  • Locally Signed Certificate: The CA certificate signs the CSR, creating a locally signed certificate for each service.

18.3. TLS Validation

To ensure secure communication, each service validates the TLS certificates using a custom validation callback. This callback is created using a utility class in ArmoniK, which checks various aspects of the certificate, such as the certificate chain, policy errors, and whether the certificate is trusted.

  • CertificateValidator Class : This class provides utilities for validating SSL/TLS certificates. It creates a callback function that validates certificates during a secure connection.

public static RemoteCertificateValidationCallback CreateCallback(string caFilePath, bool allowHostMismatch, ILogger logger)
{
    // Load the CA certificate from the file
    var content = File.ReadAllText(caFilePath);
    var authority = X509Certificate2.CreateFromPem(content);

    // Create and return the validation callback
    var callback = ValidationCallback(logger, authority, allowHostMismatch);
    return callback;
}

  • Validation Callback: The callback function checks the certificate chain, policy errors, and logs detailed information about the validation process. It ensures that the certificate is trusted and handles scenarios such as host mismatches.

    public static RemoteCertificateValidationCallback ValidationCallback(ILogger logger, X509Certificate2 authority, bool allowHostMismatch)
    {
        return (sender, certificate, chain, sslPolicyErrors) =>
        {
            // Perform validation checks and log details
            // Check for certificate chain errors, policy errors, and trust status
            return isTrusted;
        };
    }

18.4. Integration with Services

The TLS certificates and validation callback are integrated into various services within ArmoniK, including RabbitMQ, MongoDB, Redis, and AMQP. Each service uses the same validation mechanism to ensure consistent and secure communication.

  • Service Modules: Each service module (e.g., submitter, compute_plane, metrics_exporter) mounts the necessary certificates and uses the validation callback to establish secure connections.

  • Mounting Certificates: The certificates are mounted into the containers using the mounts parameter, which includes the CA certificate for validation.

18.5. Common TLS Errors and Resolutions

During the TLS validation process, several common errors can occur. Understanding these errors and their resolutions is crucial for maintaining secure communications.

  • RemoteCertificateChainErrors:

    • Definition: Indicates issues with the certificate chain, such as an untrusted root, partial chain, or revoked certificates.

    • Cause: This error occurs when the certificate chain cannot be validated due to missing or untrusted certificates.

    • Resolution: Ensure that all intermediate certificates are installed and that the root certificate is trusted. Verify that none of the certificates in the chain have been revoked or expired.

  • RemoteCertificateNameMismatch:

    • Definition: Indicates a mismatch between the certificate’s name and the hostname being connected to.

    • Cause: This error occurs when the certificate’s common name (CN) or subject alternative name (SAN) does not match the hostname.

    • Resolution: Verify that the certificate is issued for the correct hostname. If using a wildcard certificate, ensure it covers the hostname being used.

  • Certificate or Certificate Chain is Null:

    • Definition: Indicates that the certificate or certificate chain is null.

    • Cause: This error occurs when the certificate or chain cannot be retrieved or is not provided.

    • Resolution: Ensure that the certificate and chain are correctly configured and accessible.

  • Unable to Build Certificate Chain:

    • Definition: Indicates that the certificate chain cannot be built.

    • Cause: This error occurs when the certificate chain is incomplete or contains invalid certificates.

    • Resolution: Verify that all necessary certificates are present and valid. Check the chain for any missing certificates.

18.6. Conclusion

The implementation of TLS in ArmoniK ensures secure communication between services. By generating and managing certificates using Terraform and validating them with a custom callback, the project maintains a high level of security and consistency across its microservices architecture. This documentation provides an overview of the TLS implementation process and its integration into the project’s services.