Overview

Relevant source files

• README.md
• img/ai-deepwiki-anim.gif
• img/ai-deepwiki.png

Purpose and Scope

This documentation repository serves as the primary knowledge base for enabling comma.ai's openpilot driver assistance system on Toyota, Lexus, and Subaru vehicles protected by Toyota Security Key (TSK) / SecOC cryptographic security. The documentation covers the technical background, vehicle compatibility, key extraction procedures, and openpilot fork ecosystem for vehicles manufactured between 2020-2023 that implement Toyota's ECU security system.

Related Pages:

• For detailed security system architecture, see Understanding TSK/SecOC Security
• For vehicle-specific compatibility, see Vehicle Compatibility
• For step-by-step installation procedures, see Setup and Installation Guide
• For openpilot fork selection, see openpilot Fork Ecosystem
• For technical implementation details, see Technical Deep Dive

Sources: README.md1-25

The TSK/SecOC Challenge

Toyota introduced cryptographic message authentication (TSK/SecOC) on CAN bus communications starting in 2020 to prevent unauthorized vehicle control. This security system uses a vehicle-unique cryptographic key to authenticate steering control messages (STEERING_LKA), blocking third-party systems like openpilot from controlling the vehicle's latitude (steering) function.

The STEERING_LKA message on TSK-protected vehicles contains an 8-byte payload with a 4-byte authentication code, unlike the simple 5-byte message with 1-byte checksum on earlier vehicles. Without knowledge of the vehicle-specific key and authentication algorithm, openpilot cannot generate valid steering commands.

System Breakthrough: In February 2023, security researchers Willem Melching and Greg Hogan published a hardware exploit that extracts the TSK key directly from EPS ECU memory on vulnerable vehicles, enabling openpilot control while maintaining Toyota's security architecture.

Sources: README.md48-58 README.md707-718

System Architecture

Component Overview

The TSK management system consists of four primary layers:

Sources: README.md276-296 README.md464-480

Key Storage Locations

The extracted security key is stored in two persistent locations on the comma device:

Storage Path	Purpose	Persistence
/cache/params/SecOCKey	Primary key location read by auto-key-installer	Survives software updates
/data/params/d/SecOCKey	Backup key location	Survives software updates and device resets

The auto-key-installer process, introduced in January 2024, automatically loads the key from these locations on every vehicle start, eliminating the need for manual key reinstallation after openpilot updates.

Sources: README.md369 README.md464-471 README.md494

Installation Process Flow

Critical Steps:

1. Not Ready To Drive Mode: Vehicle must be in IGNITION ON state (engine not running) for exploit execution. Maximum 5 minutes to prevent 12V battery drain.
2. Exploit Execution: The hardware exploit triggers vehicle warning lights and beeps, which is expected behavior. Vehicle returns to normal after restart.
3. Key Persistence: Once extracted, the key persists across all software updates due to auto-key-installer architecture.

Sources: README.md273-418 README.md325-343

Vehicle Compatibility Landscape

Compatibility Matrix

Key Compatibility Factors:

• Bootloader Version: Vehicles with bootloader v01 on the EPS ECU are vulnerable to the exploit
• Model Year: 2020-2023 vehicles where TSK was first introduced remain exploitable
• 2024+ Block: All 2024+ models use updated bootloader v02 or v04, preventing key extraction

For detailed vehicle compatibility, see Vehicle Compatibility.

Sources: README.md72-218 README.md155-164

openpilot Fork Ecosystem

Available Branches

Fork Feature Comparison:

Fork	Lat Support	Long Support	MADS/AOL	NNLC	C3 Support	Notes
commaai/nightly-dev	✅	✅	❌	❌	❌	Official support, beta on C4
sunnypilot	✅	✅	✅	✅	✅	Community standard for TSK
FrogPilot	✅	✅	✅	❌	✅	Dangerous key delete feature
SatoPilot	✅	✅	✅	❌	✅	First fork with long support

Key Terms:

• Lat (Lateral): Steering wheel control
• Long (Longitudinal): Gas and brake pedal control
• MADS/AOL: Features that maintain steering control after brake application
• NNLC: Neural Network Lane Centering for improved steering on RAV4 Prime/Sienna

For detailed fork comparison and selection guidance, see openpilot Fork Ecosystem.

Sources: README.md512-591 README.md527-555

Security Research Timeline

The TSK bypass solution emerged from a multi-year community research effort:

Critical Innovation: The auto-key-installer (merged January 2024) transformed the system from requiring manual key reinstallation after each update to a seamless, persistent solution comparable to non-TSK vehicles.

Sources: README.md682-1137 README.md464-471

Documentation Repository Structure

This repository (optskug/docs) is primarily a single-document knowledge base:

Document Organization: The README.md file (98.1% of repository importance) contains all essential information in a single, comprehensive guide. Archive files reference Toyota's official technical portal (techinfo.toyota.com) for service procedures but are marked as "too much detail" and kept for historical reference only.

Sources: README.md1-1137 Repository file structure

Getting Started

To begin using this documentation:

1. Verify vehicle compatibility: Check Vehicle Compatibility to confirm your vehicle is supported
2. Understand the security system: Read Understanding TSK/SecOC Security for technical background
3. Follow the installation guide: Proceed to Setup and Installation Guide for step-by-step instructions
4. Select an openpilot fork: Review openpilot Fork Ecosystem for branch selection
5. Troubleshooting: Consult Troubleshooting Common Issues if issues arise

Community Support: The primary support channel is the #toyota-security channel in the comma.ai Discord (https://discord.comma.ai). Additional community resources are documented in Community Support Resources.

Sources: README.md9-24 README.md594-608