Ipsec

---
name: ipsec
description: "Expert coverage of IPsec/IKEv2 VPN across all platforms: IKEv2 negotiation, ESP, crypto suite selection, CNSA 1.0/2.0 compliance, vendor-specific configuration (Cisco, PAN-OS, FortiOS, StrongSwan), DMVPN, ADVPN, VTI, troubleshooting, and interoperability. Use for \"IPsec\", \"IKEv2\", \"site-to-site VPN\", \"crypto map\", \"VTI\", \"DMVPN\", \"ADVPN\", \"IKE proposal\", \"ESP\", \"DH group\", \"PFS\", \"NAT-T\", \"DPD\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `vpn` skill."
license: MIT
---

# IPsec/IKEv2

This skill covers IPsec/IKEv2 VPN across all major platforms. Areas of expertise include:

- IKEv2 protocol mechanics (IKE_SA_INIT, IKE_AUTH, CREATE_CHILD_SA)
- ESP encapsulation (tunnel mode, transport mode)
- Crypto suite selection (CNSA 1.0 current, CNSA 2.0 post-quantum transition)
- Vendor-specific configuration: Cisco IOS-XE, Cisco ASA, Cisco FTD, PAN-OS, FortiOS, StrongSwan
- Route-based VPN (VTI) vs policy-based (crypto map)
- Dynamic VPN architectures (DMVPN, ADVPN)
- NAT Traversal (NAT-T), DPD, PFS, anti-replay
- Multi-vendor interoperability troubleshooting

## How to Approach Tasks

1. **Classify**: Configuration, troubleshooting, algorithm selection, or architecture design
2. **Identify platforms**: Which vendors are involved? Multi-vendor interop requires careful proposal matching
3. **Load context** from `references/` for deep protocol knowledge and best practices
4. **Analyze** with protocol-level understanding (not just config templates)
5. **Recommend** with platform-specific CLI and caveats

## Crypto Suite Recommendations (2025/2026)

### CNSA 1.0 (Use Today)
```
IKE: AES-256-GCM + PRF_HMAC_SHA2_384 + ECP-384 (Group 20)
ESP: AES-256-GCM-16 + PFS Group 20
```

### CNSA 2.0 (Transition by 2033)
```
IKE: AES-256-GCM + PRF_HMAC_SHA2_384 + ML-KEM-1024 + ECP-384 (hybrid)
ESP: AES-256-GCM-16 + PFS (ML-KEM or ECP-384)
```

### Avoid
- DH Groups 1, 2, 5, 22, 23, 24 (broken/weak)
- MD5 or SHA-1 for integrity/PRF
- DES or 3DES, IKEv1

## Vendor Configuration Patterns

### Route-Based VPN (VTI) -- Preferred
VTI creates a routable tunnel interface. Supports dynamic routing (OSPF, BGP) over tunnel. Simpler than crypto maps.

**Cisco IOS-XE:**
```
crypto ikev2 proposal PROP
  encryption aes-cbc-256
  integrity sha384
  group 20

crypto ikev2 profile PROFILE
  match identity remote address <peer-ip>
  authentication remote pre-share
  authentication local pre-share
  keyring local KEYRING
  dpd 30 5 periodic

crypto ipsec transform-set TS esp-aes-gcm-256
  mode tunnel

crypto ipsec profile IPSEC-PROF
  set transform-set TS
  set ikev2-profile PROFILE
  set pfs group20

interface Tunnel1
  ip address 10.255.0.1 255.255.255.252
  tunnel source GigabitEthernet0/0
  tunnel destination <peer-ip>
  tunnel mode ipsec ipv4
  tunnel protection ipsec profile IPSEC-PROF
```

**PAN-OS:** IKE Crypto Profile + IKE Gateway + IPsec Crypto Profile + IPsec Tunnel (tunnel.x interface). See `references/architecture.md` for full config.

**FortiOS:** `config vpn ipsec phase1-interface` + `config vpn ipsec phase2-interface`. Route-based by default (creates tunnel interface).

**StrongSwan:** `swanctl.conf` with connections/children blocks. See `references/architecture.md`.

### Policy-Based VPN (Crypto Map) -- Legacy
Uses ACLs to define "interesting traffic." Harder to scale. No dynamic routing over tunnel.

## Deployment Topologies

### Point-to-Point
Two gateways, fixed peers, static or BGP routing. Simplest topology.

### Hub-and-Spoke
Central hub with per-spoke tunnels. Spoke-to-spoke via hub unless shortcuts.

### DMVPN (Cisco)
mGRE + IPsec + NHRP + dynamic routing:
- Phase 1: All traffic via hub
- Phase 2: Spoke-to-spoke shortcuts via NHRP redirect
- Phase 3: NHRP shortcut routing; direct spoke-to-spoke after discovery
- Scales to thousands of spokes

### ADVPN (Fortinet/Juniper)
Hub notifies spokes of better paths via IKEv2 extensions:
- Hub: `set auto-discovery-sender enable`
- Spoke: `set auto-discovery-receiver enable`
- Spokes establish direct IPsec SAs after hub-facilitated discovery
- ADVPN 2.0 (FortiOS 7.6+): Enhanced shortcut management for multiple underlays

## Troubleshooting

### Phase 1 Failures
- **Proposal mismatch**: Most common. Verify both sides have overlapping encryption + integrity + DH group + PRF.
- **Auth failure**: PSK case-sensitive mismatch, cert untrusted, wrong identity type (FQDN vs IP)
- **Reachability**: UDP/500 and UDP/4500 must be open. ESP (protocol 50) for non-NAT-T.
- **Clock skew**: >5 minutes breaks certificate validation. NTP critical.

### Phase 2 Failures
- **PFS mismatch**: One side requires PFS (DH group), other sends PFS=none. Fails silently or TS_UNACCEPTABLE.
- **Traffic selector mismatch**: Subnet disagreement between peers. Check local/remote selectors.
- **Anti-replay drops**: Increase replay window to 512 or 1024 for high-throughput or asymmetric routing.

### Debug Commands by Vendor

**Cisco IOS-XE:** `debug crypto ikev2 protocol` / `show crypto ikev2 sa` / `show crypto ipsec sa`
**Cisco ASA:** `debug crypto ikev2 protocol 255` / `show crypto ikev2 sa` / `show vpn-sessiondb l2l`
**FortiOS:** `diagnose debug application ike -1` + `diagnose vpn tunnel list` + `diagnose vpn ike gateway list`
**PAN-OS:** `show vpn ike-sa` / `show vpn ipsec-sa` / `test vpn ike-sa gateway <name>`
**StrongSwan:** `swanctl --list-sas` / `swanctl --log` / `journalctl -u strongswan`

## Best Practices

1. **Use IKEv2 exclusively** -- Disable IKEv1/ISAKMP where not required
2. **Route-based (VTI) over policy-based (crypto map)** for dynamic routing and simpler management
3. **Enable NAT-T on all configurations** even if NAT not currently present
4. **Certificate auth over PSK** for large deployments (>10 tunnels)
5. **Enable PFS on all Child SAs** -- DH Group 20 or higher
6. **DPD on all tunnels** -- 30-60s interval, restart action
7. **Unique traffic selectors per Child SA** for simpler troubleshooting
8. **Test DPD behavior** -- Simulate peer failure to verify cleanup and re-initiation

## Common Pitfalls

1. **AEAD with integrity algorithm**: When using AES-GCM (AEAD), do NOT include a separate integrity algorithm in the same IKE proposal. Include an explicit PRF instead.
2. **Crypto map vs VTI mixing**: Don't mix both approaches on the same interface or for the same peer.
3. **NAT-T keepalive timeout**: If NAT device has aggressive timeout, increase keepalive frequency or enable keepalives on both sides.
4. **IKEv1/IKEv2 mismatch**: Some legacy peers require IKEv1. Verify compatibility before assuming IKEv2.
5. **Certificate EKU**: Server certs need serverAuth, client certs need clientAuth in Extended Key Usage.

## Reference Files

- `references/architecture.md` -- Protocol details, IKEv2 exchange mechanics, ESP/AH, vendor configs (Cisco IOS-XE, ASA, PAN-OS, FortiOS, StrongSwan), deployment topologies.
- `references/best-practices.md` -- Algorithm recommendations (CNSA 1.0/2.0), lifetime settings, DPD, anti-replay, general VPN design principles.