mlkem-native

mlkem-native — это безопасная, быстрая и переносимая реализация ML-KEM¹ на C90². Она является форком эталонной реализации ML-KEM³.

Весь код на C в mlkem/src/* и mlkem/src/fips202/* доказанно безопасен по памяти (без переполнения памяти) и безопасен по типам (без переполнения целых чисел) с использованием CBMC⁴. Весь ассемблер для AArch64 и x86_64 доказанно функционально корректен, безопасен по памяти и имеет независимое от секретов время выполнения (constant-time), с использованием HOL-Light⁵.

mlkem-native включает нативные бэкенды для Arm (64-бит, Neon), Intel/AMD (64-бит, AVX2), RISC-V (64-бит, RVV) и POWER (ppc64le, VSX). См. benchmarks для данных о производительности.

mlkem-native поддерживается Post-Quantum Cryptography Alliance в составе Linux Foundation.

Быстрый старт для Ubuntu

# Install base packages
sudo apt-get update
sudo apt-get install make gcc python3 git

# Clone mlkem-native
git clone https://github.com/pq-code-package/mlkem-native.git
cd mlkem-native

# Build and run tests
make build
make test

# The same using `tests`, a convenience wrapper around `make`
./scripts/tests all
# Show all options
./scripts/tests --help

См. BUILDING.md для получения дополнительной информации.

Применение

mlkem-native используется в

• libOQS проекта Open Quantum Safe начиная с 0.13.0 (как реализация ML-KEM по умолчанию)
• Криптографической библиотеке AWS AWS-LC начиная с v1.50.0
• TLS-библиотеке rustls, написанной на Rust, начиная с 0.23.28 (через AWS-LC как провайдер криптографии по умолчанию)
• Pavona — библиотеке модульных, проверенных в производстве и безопасных по умолчанию открытых кремниевых блоков

Формальная верификация

Весь код на C в mlkem/src/* и mlkem/src/fips202/* доказанно безопасен по памяти (без переполнения памяти) и безопасен по типам (без переполнения целых чисел). Для этого используется C Bounded Model Checker (CBMC), и это опирается на контракты функций и аннотации инвариантов циклов в исходном коде. См. proofs/cbmc для подробностей.

Весь ассемблер для AArch64 и x86_64 доказанно функционально корректен, безопасен по памяти и имеет независимое от секретов время выполнения (constant-time), на уровне объектного кода. Для этого используется интерактивный доказатель теорем HOL-Light и инфраструктура верификации s2n-bignum (которая включает модели соответствующих частей архитектур Arm и x86). См. proofs/hol_light для подробностей.

ПРИМЕЧАНИЕ: Формальная верификация никогда не является абсолютной. См. SOUNDNESS.md для подробного анализа области применения, допущений и рисков усилий по формальной верификации вокруг mlkem-native.

Безопасность

Весь ассемблер для AArch64 и x86_64 в mlkem-native формально доказан в HOL Light как свободный от зависимых от секретов потоков управления, шаблонов доступа к памяти и инструкций с переменной задержкой, что предотвращает большинство побочных каналов по времени (см. proofs/hol_light для подробностей). Код на C защищён от побочных каналов по времени, вносимых компилятором (таких как KyberSlash⁶ или clangover⁷), с помощью соответствующих барьеров и шаблонов constant-time.

Отсутствие зависимых от секретов ветвлений, шаблонов доступа к памяти и инструкций с переменной задержкой также тестируется с помощью valgrind с различными комбинациями компиляторов и параметров компиляции.

Другие атаки. mlkem-native нацелен на устойчивость только к побочным каналам по времени. Другие классы атак, такие как побочные каналы по питанию и электромагнитному излучению, микроархитектурные побочные каналы (например, спекулятивное выполнение) или атаки с внедрением сбоев, в настоящее время выходят за рамки.

Дизайн

mlkem-native разделён на фронтенд и два бэкенда для арифметики и FIPS202 / SHA3. Фронтенд фиксирован, написан на C и охватывает все процедуры, которые не критичны для производительности. Бэкенды гибкие, отвечают за производительно-критичные процедуры и могут быть реализованы на C или в нативном коде (ассемблер/интринсики); см. mlkem/src/native/api.h для арифметического бэкенда и mlkem/src/fips202/native/api.h для бэкенда FIPS-202.

mlkem-native в настоящее время предлагает следующие бэкенды:

• Бэкенд на переносимом C по умолчанию
• 64-битный бэкенд Arm (с использованием Neon)
• 64-битный бэкенд Intel/AMD (с использованием AVX2)
• 64-битный бэкенд RISC-V (с использованием RVV)
• 64-битный бэкенд POWER (ppc64le, с использованием VSX; поддерживает POWER8 и выше)
• 32-битный бэкенд Armv8.1-M (с использованием Helium/MVE) — см. #1501. Он всё ещё экспериментальный и отключён по умолчанию.

Если вы хотите внести вклад в новые бэкенды, пожалуйста, свяжитесь с нами или просто откройте PR.

Наш ассемблер для AArch64 разработан с использованием супероптимизатора SLOTHY, следуя подходу, описанному в статье о SLOTHY⁸: Мы пишем «чистый» ассемблер вручную и автоматизируем микрооптимизации (например, см. clean против optimized NTT для AArch64). См. dev/README.md для более подробной информации.

Тестовые векторы

mlkem-native тестируется на всех официальных ACVP ML-KEM тестовых векторах⁹ и тестовых векторах ML-KEM Wycheproof¹⁰.

ACVP

Вы можете запустить тесты ACVP с помощью скрипта tests или напрямую ACVP-клиента:

# Using the tests script
./scripts/tests acvp
# Using a specific ACVP release
./scripts/tests acvp --version v1.1.0.41

# Using the ACVP client directly
python3 ./test/acvp/acvp_client.py
python3 ./test/acvp/acvp_client.py --version v1.1.0.41

# Using specific ACVP test vector files (downloaded from the ACVP-Server)
# python3 ./test/acvp/acvp_client.py -p {PROMPT}.json -e {EXPECTED_RESULT}.json
# For example, assuming you have run the above
python3 ./test/acvp/acvp_client.py \
  -p ./test/acvp/.acvp-data/v1.1.0.41/files/ML-KEM-keyGen-FIPS203/prompt.json \
  -e ./test/acvp/.acvp-data/v1.1.0.41/files/ML-KEM-keyGen-FIPS203/expectedResults.json

Wycheproof

Вы можете запустить тесты Wycheproof¹⁰ с помощью скрипта tests или напрямую Wycheproof-клиента:

# Using the tests script
./scripts/tests wycheproof

# Using the Wycheproof client directly
python3 ./test/wycheproof/wycheproof_client.py

Бенчмаркинг

Вы можете измерить производительность, использование памяти и размер двоичного файла с помощью скрипта tests:

# Speed benchmarks (-c selects cycle counter: NO, PMU, PERF, or MAC)
# Note: PERF/MAC may require the -r flag to run benchmarking binaries using sudo
./scripts/tests bench -c PMU
./scripts/tests bench -c PERF -r

# Stack usage analysis
./scripts/tests stack

# Binary size measurement
./scripts/tests size

Для результатов бенчмарков CI и исторических данных о производительности см. страницу бенчмарков.

Использование

Если вы хотите использовать mlkem-native, импортируйте mlkem в дерево исходников вашего проекта и соберите с помощью вашей любимой системы сборки. См. mlkem для получения дополнительной информации, и examples/basic для простого примера. Система сборки, предоставленная в этом репозитории, предназначена только для целей разработки.

См. API-CONVENTIONS.md для соглашений, которые применяются ко всем публичным функциям, таких как возвращаемые значения, допустимость указателей и состояние выходных буферов при ошибке.

Могу ли я использовать свой собственный FIPS-202?

mlkem-native полагается на реализацию FIPS-202¹¹ и поставляется с ней. Если ваша библиотека имеет собственную реализацию FIPS-202, вы можете использовать её вместо той, что поставляется с mlkem-native. См. FIPS202.md и examples/bring_your_own_fips202 для примера с использованием tiny_sha3¹².

Нужно ли мне использовать ассемблерные бэкенды?

Нет. Если вам нужна сборка только на C, просто исключите каталоги mlkem/src/native и/или mlkem/src/fips202/native из вашего импорта и сбросьте MLK_CONFIG_USE_NATIVE_BACKEND_ARITH и/или MLK_CONFIG_USE_NATIVE_BACKEND_FIPS202 в вашем mlkem_native_config.h.

Нужно ли мне настраивать CBMC для использования mlkem-native?

Нет. Хотя мы рекомендуем рассмотреть возможность его использования, mlkem-native будет собираться и работать нормально без CBMC — просто убедитесь, что включён cbmc.h и CBMC не определён. В частности, вам не нужно удалять все контракты функций и инварианты циклов из кода; они будут игнорироваться, если только CBMC не установлен.

Поддерживает ли mlkem-native все уровни безопасности ML-KEM?

Да. Уровень безопасности — это параметр времени компиляции, настраиваемый установкой MLK_CONFIG_PARAMETER_SET=512/768/1024 в mlkem_native_config.h. Если ваша библиотека/приложение требует несколько уровней безопасности, вы можете собрать и слинковать три экземпляра mlkem-native, разделяя общий код; это называется «многоуровневой сборкой» и продемонстрировано в examples/multilevel_build. См. также mlkem.

Могу ли я принести свой собственный бэкенд?

Да, вы можете добавить дополнительные бэкенды для нативной арифметики ML-KEM и/или для FIPS-202. Используйте существующие бэкенды в качестве шаблонов или см. examples/custom_backend для минимального примера того, как зарегистрировать пользовательский бэкенд.

Есть вопрос?

Если вы считаете, что нашли уязвимость в безопасности mlkem-native, пожалуйста, сообщите о ней через приватный отчёт об уязвимостях Github. Пожалуйста, не создавайте публичный issue на GitHub.

Если у вас есть любой другой вопрос / проблема, не связанная с безопасностью / запрос функции, пожалуйста, откройте issue на GitHub.

Внесение вклада

Если вы хотите помочь нам в разработке mlkem-native, пожалуйста, свяжитесь с нами. Вы можете связаться с командой mlkem-native через PQCA Discord. См. также CONTRIBUTING.md.