OPTEE OemLock HAL Implementation

This implementation provides the OemLock HAL with AVB support via OP-TEE, using secure persistent storage.

Architecture

Android Side (HAL)

• Service : android.hardware.oemlock-service.optee
• Interface : AIDL android.hardware.oemlock.IOemLock
• Storage Backend : TA AVB persistent values via OP-TEE RPMB
• Legacy Properties (maintained for compatibility):
  • ro.boot.carrier_unlock_allowed : Carrier authorization (read-only)
  • persist.vendor.oemlock.device_unlock_allowed : Device/user authorization

Bootloader Side (U-Boot)

• Fastboot Commands :
  • fastboot flashing unlock : Unlock the device
  • fastboot flashing lock : Lock the device
  • fastboot getvar unlocked : Get unlock/lock state
  • fastboot flashing get_unlock_ability : Get unlock ability
• Storage Backend : TA AVB persistent values via OP-TEE RPMB
• Persistent Key : "unlock_ability" (shared with Android HAL)

Secure Persistent Storage Flow

Data Flow Architecture

Android Settings → OEMlock HAL → TA AVB Persist Storage ← U-Boot Fastboot
     ↓                ↓              ↓                      ↓
  User Toggle → setOemUnlockAllowed → "unlock_ability" → get_unlock_ability

Storage Implementation

• Primary: TA AVB persistent values (key: "unlock_ability")
• Secondary: Legacy lock state commands (backward compatibility)
• Security: RPMB storage through OP-TEE secure world
• Consistency: Single source of truth across Android and U-Boot

Usage Flow

1. Enable OEM Unlocking

# From Android Settings
Settings → System → Developer options → OEM unlocking [ON]

2. Unlock via fastboot

# Check unlock ability
fastboot flashing get_unlock_ability  # Should return "1"

# Unlock (with confirmation)
fastboot flashing unlock
# WARNING: Unlocking the bootloader will void your warranty...
# Type 'yes' to confirm unlock: yes

# Verify state
fastboot getvar unlocked  # Should return "yes"

3. Lock via fastboot

# Lock
fastboot flashing lock

# Verify state
fastboot getvar unlocked  # Should return "no"

Configuration

AndroidBoard.mk

PRODUCT_PACKAGES += android.hardware.oemlock-service.optee

device.mk

# OemLock HAL
PRODUCT_COPY_FILES += \
    hardware/ti/am62x/oemlock/android.hardware.oemlock-service.optee.rc:$(TARGET_COPY_OUT_VENDOR)/etc/init/android.hardware.oemlock-service.optee.rc

DEVICE_MANIFEST_FILE += hardware/ti/am62x/oemlock/android.hardware.oemlock-service.optee.xml

U-Boot Configuration

CONFIG_OPTEE_TA_AVB=y
CONFIG_FASTBOOT=y
CONFIG_FASTBOOT_FLASH=y

OP-TEE TA AVB Features

• TA_AVB_CMD_READ_PERSIST_VALUE : Read persistent values
• TA_AVB_CMD_WRITE_PERSIST_VALUE : Write persistent values
• TA_AVB_CMD_READ_LOCK_STATE : Read legacy lock state
• TA_AVB_CMD_WRITE_LOCK_STATE : Write legacy lock state

Security

Protection Mechanisms

1. Dual Authorization : Carrier + User consent required
2. User Confirmation : Interactive unlock confirmation in fastboot
3. Factory Reset : Recommended after unlock for security
4. Secure Storage : RPMB via OP-TEE secure world
5. Tamper Resistance : Persistent values cannot be modified without proper authorization

Persistent Properties

• Secure Persistence : Unlock state survives reboots and factory resets
• Cross-Platform Sync : Android ↔ Bootloader synchronization via TA AVB
• Bypass Protection : No environment variable dependencies
• State Consistency : Single source of truth in secure storage

Key Advantages Over Environment Variables

• Security : Stored in RPMB, not in volatile environment
• Persistence : Survives U-Boot environment resets
• Consistency : Shared between Android HAL and U-Boot fastboot
• Tamper Resistance : Protected by OP-TEE security model

Testing and Validation

Android Tests

# Via adb - check legacy properties
adb shell getprop ro.boot.flash.locked
adb shell getprop persist.vendor.oemlock.device_unlock_allowed

# Via Settings UI
Settings → System → Developer options → OEM unlocking

# HAL service logs
adb logcat | grep -i oemlock

Fastboot Tests

# Basic state checks
fastboot flashing get_unlock_ability  # Should return "1" if enabled
fastboot getvar unlocked              # Current lock state

# Full unlock/lock cycle
fastboot flashing unlock      # Unlock with confirmation
fastboot getvar unlocked      # Should return "yes"
fastboot flashing lock        # Lock device
fastboot getvar unlocked      # Should return "no"

# Critical partitions (if implemented)
fastboot getvar critical_unlocked
fastboot flashing unlock_critical
fastboot flashing lock_critical

TA AVB Storage Verification

# In U-Boot console (for debugging)
=> optee_avb read_persist unlock_ability
=> optee_avb write_persist unlock_ability 1

Troubleshooting

Common Issues

1. unlock_ability = 0

   • Check OEM unlocking in Developer Options
   • Verify TA AVB persist storage: optee_avb read_persist unlock_ability
   • Check HAL logs: adb logcat | grep -i oemlock

2. TA AVB communication failed

   • Verify CONFIG_OPTEE_TA_AVB=y in U-Boot
   • Check OP-TEE and TA AVB are loaded correctly
   • Verify RPMB storage is accessible

3. Permission denied

   • Check service user/group permissions
   • Verify SELinux policies for HAL service
   • Ensure libteec permissions are correct

4. State inconsistency

   • HAL detects and auto-corrects inconsistencies
   • Check HAL initialization logs for sync messages
   • Verify both persist values and legacy properties

Debug Commands

# U-Boot debugging
=> optee_avb read_persist unlock_ability
=> optee_avb read_lock_state
=> printenv fastboot.unlock_ability  # Legacy (should be deprecated)

# Android debugging
adb logcat | grep -i oemlock
adb logcat | grep -i "TA AVB"
adb shell getprop | grep unlock

Migration from Environment Variables

If migrating from environment variable implementation:

1. HAL will auto-sync on first boot
2. Check HAL logs for "Syncing unlock ability" messages
3. Verify persist storage contains correct values
4. Environment variables are maintained for compatibility but not used

Implementation Details

HAL Service Files

• OemLock.h : Header with TA AVB command definitions
• OemLock.cpp : Main HAL implementation with persist value support
• service.cpp : Service entry point
• Android.bp : Build configuration

Key Functions

• readPersistValue() : Read from TA AVB secure storage
• writePersistValue() : Write to TA AVB secure storage
• setOemUnlockAllowedByDevice() : Update unlock ability
• isOemUnlockAllowedByDevice() : Query unlock ability

Persistent Storage Keys

• "unlock_ability" : Combined unlock state (carrier && device)
• "critical_lock_state" : Critical partitions lock state