chore(elbv2): add post-quantum cryptography SSL policies

[pahud]

Issue # (if applicable)

Closes #36283.

Reason for this change

AWS announced support for post-quantum (PQ) security policies for Application Load Balancers and Network Load Balancers on November 21, 2025. These policies use hybrid post-quantum key exchange with ML-KEM (Module-Lattice-Based Key-Encapsulation Mechanism) to protect against "Harvest Now, Decrypt Later" attacks. The CDK's SslPolicy enum currently lacks these new policies, forcing users to use string literals and losing type safety.

Description of changes

Added 14 new post-quantum security policy enum values to the SslPolicy enum in packages/aws-cdk-lib/aws-elasticloadbalancingv2/lib/shared/enums.ts:

Standard TLS Policies with PQ:

• TLS13_13_PQ - TLS 1.3 only with post-quantum hybrid key exchange
• TLS13_12_PQ - TLS 1.2 and 1.3 with post-quantum hybrid key exchange
• TLS13_12_RES_PQ - TLS 1.2 and 1.3 restricted cipher suite with PQ (AWS recommended)
• TLS13_12_EXT1_PQ - TLS 1.2 and 1.3 extended cipher suite 1 with PQ
• TLS13_12_EXT2_PQ - TLS 1.2 and 1.3 extended cipher suite 2 with PQ
• TLS13_10_PQ - TLS 1.0 through 1.3 with post-quantum hybrid key exchange

FIPS-Compliant Policies with PQ:

• FIPS_TLS13_13_PQ - TLS 1.3 only FIPS-compliant with PQ
• FIPS_TLS13_12_PQ - TLS 1.2 and 1.3 FIPS-compliant with PQ
• FIPS_TLS13_12_RES_PQ - TLS 1.2 and 1.3 restricted FIPS-compliant with PQ (AWS recommended for FIPS)
• FIPS_TLS13_12_EXT0_PQ - TLS 1.2 and 1.3 extended cipher suite 0 FIPS-compliant with PQ
• FIPS_TLS13_12_EXT1_PQ - TLS 1.2 and 1.3 extended cipher suite 1 FIPS-compliant with PQ
• FIPS_TLS13_12_EXT2_PQ - TLS 1.2 and 1.3 extended cipher suite 2 FIPS-compliant with PQ
• FIPS_TLS13_11_PQ - TLS 1.1 through 1.3 FIPS-compliant with PQ
• FIPS_TLS13_10_PQ - TLS 1.0 through 1.3 FIPS-compliant with PQ

All enum values map to their corresponding AWS policy names (e.g., ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09) and include JSDoc comments describing their purpose and quantum resistance capabilities.

This is a purely additive change with no breaking changes. All existing enum values remain unchanged.

Description of changes to permissions

N/A - This change only adds enum values and does not modify IAM permissions or resource access patterns.

Description of how you validated changes

• Unit tests: Verified enum values compile correctly and match AWS policy naming conventions
• Integration tests: Confirmed enum values can be used in load balancer listener configurations
• AWS CLI validation: Used aws elbv2 describe-ssl-policies to verify post-quantum policy names exist in AWS

Official AWS Documentation Proof:

All 14 policy names are documented in the official AWS ELB documentation:

• Application Load Balancer Security Policies - Protocols by policy table
• Network Load Balancer Security Policies

The documentation explicitly lists all PQ policies in the "Protocols by policy" and "Ciphers by policy" tables, including:

• Standard TLS policies: ELBSecurityPolicy-TLS13-1-3-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Ext1-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Ext2-PQ-2025-09, ELBSecurityPolicy-TLS13-1-0-PQ-2025-09
• FIPS policies: ELBSecurityPolicy-TLS13-1-3-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Res-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Ext0-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Ext1-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-2-Ext2-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-1-FIPS-PQ-2025-09, ELBSecurityPolicy-TLS13-1-0-FIPS-PQ-2025-09

AWS documentation states: "Security policies with PQ in their names offer hybrid post-quantum key exchange. For compatibility, they support both classical and post-quantum ML-KEM key exchange algorithms."

Live AWS API Validation:

Validation script (poc.sh) confirmed 13 of 14 policies are currently available via the AWS API:

✓ ELBSecurityPolicy-TLS13-1-3-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Ext1-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Ext2-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-0-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-3-FIPS-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-FIPS-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Res-FIPS-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Ext0-FIPS-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Ext1-FIPS-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-2-Ext2-FIPS-PQ-2025-09
✓ ELBSecurityPolicy-TLS13-1-0-FIPS-PQ-2025-09

Note: ELBSecurityPolicy-TLS13-1-1-FIPS-PQ-2025-09 is documented but not yet available in the live AWS API (may be rolling out or region-specific). All enum values match the official AWS documentation.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[alexw91]

Can you also update RECOMMENDED_TLS to ELBSecurityPolicy-TLS13-1-2-PQ-2025-09? It is purely additive, and I'd love to see the default recommended policy be post-quantum secure as well!

[pahud]

Can you also update RECOMMENDED_TLS to ELBSecurityPolicy-TLS13-1-2-PQ-2025-09? It is purely additive, and I'd love to see the default recommended policy be post-quantum secure as well!

Sure I will look into this and update this PR.

[pahud]

Can you also update RECOMMENDED_TLS to ELBSecurityPolicy-TLS13-1-2-PQ-2025-09? It is purely additive, and I'd love to see the default recommended policy be post-quantum secure as well!

AWS recommends implementing the new post-quantum TLS (PQ-TLS) based security policy  ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09 or ELBSecurityPolicy-TLS13-1-2-FIPS-PQ-2025-09.
Console – The default security policy is ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09
Other methods (for example, the AWS CLI, AWS CloudFormation, and the AWS CDK) – The default security policy is ELBSecurityPolicy-2016-08.

https://docs.aws.amazon.com/elasticloadbalancing/latest/application/describe-ssl-policies.html

Method	Current Default SSL Policy	Post-Quantum?	Year
AWS Console	ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09	✅ Yes	2025
AWS CLI	ELBSecurityPolicy-2016-08	❌ No	2016
CloudFormation	ELBSecurityPolicy-2016-08	❌ No	2016
CDK RECOMMENDED_TLS	ELBSecurityPolicy-TLS13-1-2-2021-06	❌ No	2021
CloudFormation Examples	ELBSecurityPolicy-TLS13-1-2-2021-06	❌ No	2021
AWS Recommendation	ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09	✅ Yes	2025

Key Discrepancy: The AWS Console already defaults to post-quantum security, but all programmatic methods (CLI, CloudFormation, CDK) still use older, non-post-quantum policies. This creates an inconsistent experience where Console users get better security by default than infrastructure-as-code users.

I am on board to make CDK default to ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09 but changing the RECOMMENDED_TLS would cause breaking change which is subject to resource replacement with disruptions.

We have two options here to move this path forward:

Option 1: Feature Flag

// Add a new feature flag
RECOMMENDED_TLS_PQ = 'ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09'

// Keep existing for backward compatibility
RECOMMENDED_TLS = 'ELBSecurityPolicy-TLS13-1-2-2021-06'

Users opt-in via CDK feature flags:

// cdk.json
{
  "context": {
    "@aws-cdk/aws-elasticloadbalancingv2:usePostQuantumTlsPolicy": true
  }
}

export enum SslPolicy {
  /**
   * The recommended security policy for TLS listeners.
   *
   * When feature flag @aws-cdk/aws-elasticloadbalancingv2:usePostQuantumTlsPolicy is enabled,
   * this uses ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09 (post-quantum).
   * Otherwise uses ELBSecurityPolicy-TLS13-1-2-2021-06 (legacy).
   */
  RECOMMENDED_TLS = // dynamically determined based on feature flag
    FeatureFlags.of(this).isEnabled(ELB_USE_POST_QUANTUM_TLS_POLICY)
      ? 'ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09'
      : 'ELBSecurityPolicy-TLS13-1-2-2021-06',
}

Result:

• Feature flag disabled (default): SslPolicy.RECOMMENDED_TLS = old policy (no BC)
• Feature flag enabled: SslPolicy.RECOMMENDED_TLS = post-quantum policy

This way existing code using SslPolicy.RECOMMENDED_TLS gets the new behavior only when users explicitly opt-in via the feature flag.

Option 2: New Enum Value

// Add alongside existing
RECOMMENDED_TLS = 'ELBSecurityPolicy-TLS13-1-2-2021-06'        // unchanged
RECOMMENDED_TLS_PQ = 'ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09'  // new

export enum SslPolicy {
  /**
   * The recommended security policy for TLS listeners.
   * This policy includes TLS 1.3, and is backwards compatible with TLS 1.2
   */
  RECOMMENDED_TLS = 'ELBSecurityPolicy-TLS13-1-2-2021-06',  // UNCHANGED

  /**
   * The recommended post-quantum security policy for TLS listeners.
   * AWS recommended policy for post-quantum cryptography.
   */
  RECOMMENDED_TLS_PQ = 'ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09',  // NEW
}

Behavior:

• No breaking change: Existing code using SslPolicy.RECOMMENDED_TLS continues working exactly as before
• Opt-in upgrade: Users who want post-quantum security can explicitly use SslPolicy.RECOMMENDED_TLS_PQ
• Clear intent: The naming makes it obvious which one provides post-quantum protection

Personally, if the console now defaults to TLS_PQ, I don't see any reason CDK should not by introducing a FF. Let me know if there's any other concerns.

[alexw91]

I'm in favor of Option 1: Feature Flag. I believe that eventually we will want to set it to true by default for everyone, but this allows customers interested in being early adopters to enable it for themselves early.