Feature Discussion: Native Support for TLS Data Access in RoadRunner for mTLS with NIST 800-204B Compliance

[Zorzi23]

Feature Discussion: Native Support for TLS Data Access in RoadRunner for mTLS with NIST 800-204B Compliance

Background

I am working on implementing a secure Mutual TLS (mTLS) setup in a RoadRunner-based application to meet the requirements outlined in NIST Special Publication 800-204B, "Security Strategies for Microservices-based Application Systems." Specifically, NIST 800-204B emphasizes secure communication between microservices, including the use of mTLS for mutual authentication, certificate-based identity verification, and fine-grained access control (Section 3.2, "Secure Service-to-Service Communication").

To support mTLS in RoadRunner, we need access to TLS certificate details (e.g., client certificate's subject, issuer, serial number, and validity) within the HTTP middleware or PHP workers. While RoadRunner's HTTP plugin supports TLS configuration (e.g., client_auth_type: request_client_cert or require_and_verify_client_cert), there is no built-in mechanism to expose detailed TLS data to the application layer (e.g., PHP workers) for processing or validation, which is critical for implementing NIST 800-204B-compliant mTLS workflows.

Problem Statement

Currently, to access TLS certificate information (such as r.TLS.PeerCertificates in Go), a custom middleware plugin must be developed to extract this data and pass it to the PHP worker via the request context (e.g., using request->getAttribute()). This approach works but requires significant custom development, which may not be ideal for all users. Additionally, ensuring compliance with NIST 800-204B (e.g., validating certificate attributes, enforcing certificate pinning, or integrating with external identity providers) adds complexity without native support.

I would like to discuss the possibility of adding native support in RoadRunner for accessing TLS certificate details, either through the HTTP plugin or a dedicated mTLS plugin, to simplify mTLS implementations and ensure alignment with NIST 800-204B guidelines.

Proposed Feature

I propose one or more of the following enhancements to RoadRunner:

1. Native TLS Data Exposure in HTTP Plugin:
   • Add a built-in mechanism in the HTTP plugin to automatically extract and expose TLS certificate details (e.g., subject, issuer, serial number, validity dates, and SANs) to PHP workers via request attributes or headers.
   • Example: Make r.TLS.PeerCertificates data available as a standardized attribute (e.g., $request->getAttribute('tls_info')) without requiring a custom middleware.
2. Dedicated mTLS Plugin:
   • Introduce an official plugin (e.g., mtls) that handles mTLS-specific tasks, such as:
     • Parsing and validating client certificates against a trust store.
     • Enforcing NIST 800-204B requirements, such as certificate-based authentication and authorization.
     • Providing configurable options for certificate validation (e.g., checking revocation status via OCSP or CRL).
   • This plugin could integrate with the HTTP middleware chain and expose data to workers.
3. Configuration Enhancements:
   • Extend the .rr.yaml HTTP SSL configuration to include options for mTLS-specific settings, such as:
     • Specifying trusted CA certificates for client verification.
     • Configuring certificate attribute mappings for easier access in workers.
     • Enabling/disabling specific TLS validation checks (e.g., expiry, hostname, or key usage).
4. Documentation and Examples:
   • Provide official documentation and example code (Go and PHP) for implementing mTLS with RoadRunner, including NIST 800-204B compliance considerations (e.g., secure key management, certificate rotation, and auditing).

Use Case

A common use case is a microservices architecture where RoadRunner-based services require mutual authentication via mTLS. For example:

• A client service sends a request with a client certificate.
• The RoadRunner server verifies the certificate and extracts attributes (e.g., subject DN or SAN) to enforce access control or log audit trails, as required by NIST 800-204B.
• The extracted TLS data is used in the PHP worker to map the client certificate to an application-level identity or role.

Without native support, developers must write custom Go plugins, which increases complexity and maintenance overhead.

NIST 800-204B Relevance

NIST 800-204B highlights several requirements for mTLS in microservices, including:

• Mutual Authentication: Both client and server must authenticate using certificates (Section 3.2.1).
• Certificate Validation: Verify certificate attributes, such as issuer, validity, and key usage (Section 3.2.3).
• Secure Key Management: Ensure proper handling of private keys and trust stores (Section 3.3).
• Auditability: Log certificate details for security auditing (Section 4.2).

Native support in RoadRunner would simplify compliance with these requirements by providing standardized access to TLS data and validation mechanisms.

[rustatian]

Hey @Zorzi23 👋🏻
Thank you for the detailed proposal 👍🏻. Yes, we discussed (I believe a year ago) the possibility of passing that information to the PHP worker, but IIRC, it was not implemented. This should not be complicated to add an official middleware to provide such information for the PHP Worker. I can create a middleware if you'd be able to help me test it (I'm not a PHP dev, only Go-related parts).

[rustatian]

@Zorzi23 I can send you a pre-release-binary here, what OS + Arch do you use for tests?

[Zorzi23]

@rustatian Currently, I use Ubuntu (Linux) with WSL for testing.

[rustatian]

Here you are: https://www.dropbox.com/t/Hj58KwBYDz7wO5ZO
I can't attach binaries here, unfortunately. I've added 2 files, exe for Windows and binary for Linux.
Here you may find a PR: roadrunner-server/http#210
Feel free to check if all the needed info is propagated to the PHP worker.

[rustatian]

@Zorzi23 Btw, RR itself supports mTLS: https://github.com/roadrunner-server/roadrunner/blob/master/.rr.yaml#L911 (require_and_verify_client_cert). Could you please elaborate, why do you need TLS info in the HTTP worker?

[Zorzi23]

Hi @rustatian !

Thank you so much for the pre-release binary and the PR! I'll test it this week on my WSL/Ubuntu environment and provide detailed feedback.

Regarding your question about needing TLS data in the HTTP worker, here's my specific use case: I'm implementing a vault microservice with rr + spiral where:

Attribute-Based Access Control: The client's mTLS certificate (e.g., Client A) contains custom X.509 extensions that determine what information they can access. For example:

One client might request JWK creation but only be allowed to receive the public part

Another client might have full signing permissions

Legacy Monolith Migration: In our current legacy system we have:

IoT integrations that directly inspect client SSL certificates for auditing

Access control based on certificate DNs/SANs

NIST 800-204B requirements for attribute validation (Section 3.2.3)

Currently we handle this through Apache+PHP using $_SERVER['SSL_CLIENT_S_DN'], but we want to migrate to RoadRunner while maintaining this functionality.

Your implementation in PR #210 looks perfect for these cases! I'll specifically verify:

Whether all certificate fields (Subject, Issuer, SANs, Serial) are available

If custom extensions (like Certificate Policies) are accessible

Performance under high mTLS concurrency

I'll share test results by Friday or next week. I'd be happy to contribute PHP examples to the documentation if that would help.

Best regards!