mirror of
https://github.com/apache/nuttx.git
synced 2026-10-08 06:45:19 +00:00
f6ecf80ebb
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.
This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.
What it does:
* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
its old path, so old URLs keep working. The redirect page also carries
a link's #anchor across to the new page.
Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:
index the front page
os/index OS Design
os/scheduling/index Scheduling
os/interrupts/index Interrupts
os/ipc/index IPC
os/time/index Time and timers
about/index About
developing/index Developing NuttX
ReleaseNotes/index Release notes
The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.
Nothing outside Documentation/ is touched.
How it was checked:
* Sphinx builds with -W: no warnings, and no document left outside a
toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
For every page outside the ten named above it erases what a move
touches -- link target, path, tag line, toctree block, table border --
from the whole old text and the whole new text, and requires the two
to be byte for byte identical. It also requires every sentence of a
deleted page to turn up somewhere, and every page that left its old
path to have a redirect, from a URL that existed, to where its content
went. It exits non-zero and names the page if any of that is not true,
and it tests added pages too, so forgetting to declare one cannot make
it pass.
* An independent audit checked 133 factual claims on these ten pages
against the tree, one shell command per claim: 130 confirmed, 1
refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.
The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.
Assisted-by: Claude:claude-opus-5
238 lines
6.6 KiB
ReStructuredText
238 lines
6.6 KiB
ReStructuredText
====================
|
|
Crypto API Subsystem
|
|
====================
|
|
|
|
Overview
|
|
========
|
|
|
|
The NuttX Crypto API subsystem provides a unified interface for cryptographic operations, supporting various encryption, decryption, hashing, and authentication algorithms. The subsystem abstracts hardware and software crypto implementations through a common interface.
|
|
|
|
Supported Algorithms
|
|
====================
|
|
|
|
Symmetric Encryption Algorithms
|
|
--------------------------------
|
|
|
|
**AES (Advanced Encryption Standard)**
|
|
|
|
- AES-CBC Mode:
|
|
- CRYPTO_AES_CBC (128-bit key size)
|
|
- CRYPTO_AES_192_CBC (192-bit key size)
|
|
- CRYPTO_AES_256_CBC (256-bit key size)
|
|
|
|
- AES-CTR Mode (Counter mode):
|
|
- CRYPTO_AES_CTR
|
|
|
|
- AES-XTS Mode (XEX-based Tweaked CodeBook):
|
|
- CRYPTO_AES_XTS
|
|
|
|
- AES-GCM Mode (Galois/Counter Mode):
|
|
- CRYPTO_AES_GCM_16
|
|
|
|
- AES-OFB Mode (Output Feedback):
|
|
- CRYPTO_AES_OFB
|
|
|
|
- AES-CFB Mode (Cipher Feedback):
|
|
- CRYPTO_AES_CFB_8 (8-bit)
|
|
- CRYPTO_AES_CFB_128 (128-bit)
|
|
|
|
**Other Block Cipher Modes**
|
|
|
|
- Blowfish (BLF):
|
|
- CRYPTO_BLF_CBC
|
|
|
|
- CAST (CAST-128):
|
|
- CRYPTO_CAST_CBC
|
|
|
|
- Rijndael (128-bit):
|
|
- CRYPTO_RIJNDAEL128_CBC
|
|
|
|
- Null (No encryption):
|
|
- CRYPTO_NULL
|
|
|
|
Authentication and Hashing Algorithms
|
|
--------------------------------------
|
|
|
|
**HMAC (Hash-based Message Authentication Code)**
|
|
|
|
- MD5-HMAC:
|
|
- CRYPTO_MD5_HMAC
|
|
|
|
- SHA-1 HMAC:
|
|
- CRYPTO_SHA1_HMAC
|
|
|
|
- SHA-2 HMAC:
|
|
- CRYPTO_SHA2_224_HMAC (224-bit)
|
|
- CRYPTO_SHA2_256_HMAC (256-bit)
|
|
- CRYPTO_SHA2_384_HMAC (384-bit)
|
|
- CRYPTO_SHA2_512_HMAC (512-bit)
|
|
|
|
**Hash Functions**
|
|
|
|
- MD5:
|
|
- CRYPTO_MD5
|
|
|
|
- SHA-1:
|
|
- CRYPTO_SHA1
|
|
|
|
- SHA-2:
|
|
- CRYPTO_SHA2_224 (224-bit)
|
|
- CRYPTO_SHA2_256 (256-bit)
|
|
- CRYPTO_SHA2_384 (384-bit)
|
|
- CRYPTO_SHA2_512 (512-bit)
|
|
|
|
- RIPEMD-160:
|
|
- CRYPTO_RIPEMD160 (as hash function)
|
|
- CRYPTO_RIPEMD160_HMAC
|
|
|
|
**Message Authentication Codes**
|
|
|
|
- AES-GMAC (Galois Message Authentication Code):
|
|
- CRYPTO_AES_128_GMAC (128-bit key)
|
|
- CRYPTO_AES_192_GMAC (192-bit key)
|
|
- CRYPTO_AES_256_GMAC (256-bit key)
|
|
- CRYPTO_AES_GMAC (generic)
|
|
|
|
- AES-CMAC (Cipher-based Message Authentication Code):
|
|
- CRYPTO_AES_CMAC
|
|
- CRYPTO_AES_128_CMAC (128-bit)
|
|
|
|
- Poly1305:
|
|
- CRYPTO_POLY1305
|
|
- CRYPTO_CHACHA20_POLY1305
|
|
- CRYPTO_CHACHA20_POLY1305_MAC
|
|
|
|
**Stream Ciphers**
|
|
|
|
- ChaCha20:
|
|
- CRYPTO_CHACHA20_POLY1305 (with Poly1305 MAC)
|
|
|
|
Integrity and Checksums
|
|
------------------------
|
|
|
|
- CRC-32:
|
|
- CRYPTO_CRC32
|
|
|
|
- Extended Sequence Numbers (ESN):
|
|
- CRYPTO_ESN
|
|
|
|
Compression
|
|
-----------
|
|
|
|
- Deflate Compression:
|
|
- CRYPTO_DEFLATE_COMP
|
|
|
|
Usage
|
|
=====
|
|
|
|
The Crypto API is accessed through the cryptodev interface, which provides ioctl commands for initializing cryptographic sessions and performing operations.
|
|
|
|
Basic Usage Pattern
|
|
-------------------
|
|
|
|
1. Open the cryptodev device (/dev/crypto)
|
|
2. Initialize a cryptographic session with desired algorithm
|
|
3. Submit crypto operations (encrypt/decrypt/hash)
|
|
4. Close the session when done
|
|
|
|
For more details, refer to the cryptodev.h header file and specific driver documentation.
|
|
|
|
Asymmetric Cryptography
|
|
=======================
|
|
|
|
Public Key Algorithms
|
|
---------------------
|
|
|
|
**RSA (Rivest-Shamir-Adleman)**
|
|
|
|
- RSA key pair generation for variable key sizes
|
|
- Digital signature generation and verification with multiple padding schemes:
|
|
- PKCS#1 v1.5 padding (CRK_RSA_PKCS15_SIGN, CRK_RSA_PKCS15_VERIFY)
|
|
- PSS (Probabilistic Signature Scheme) padding (CRK_RSA_PSS_SIGN, CRK_RSA_PSS_VERIFY)
|
|
- Public key encryption and decryption
|
|
- RSA operations accessible via /dev/crypto cryptodev interface
|
|
|
|
**ECDSA (Elliptic Curve Digital Signature Algorithm)**
|
|
|
|
- ECDSA key pair generation for different curves
|
|
- Digital signature generation and verification
|
|
|
|
ECC / ECDSA (Software)
|
|
----------------------
|
|
|
|
NuttX also provides a lightweight ECC implementation and public API in
|
|
``include/crypto/ecc.h``. It can be used for ECC key generation, ECDH shared
|
|
secret computation, and ECDSA sign/verify. Public key export is available in
|
|
compressed form (``ECC_BYTES + 1``) as well as X/Y uncompressed form.
|
|
|
|
RSA Digital Signature Operations
|
|
--------------------------------
|
|
|
|
The cryptodev module supports RSA digital signatures via the cryptokey interface:
|
|
|
|
- **CRK_RSA_PKCS15_SIGN**: Generate RSA signature with PKCS#1 v1.5 padding
|
|
- Input: message hash, private key ID
|
|
- Output: RSA signature
|
|
|
|
- **CRK_RSA_PKCS15_VERIFY**: Verify RSA signature with PKCS#1 v1.5 padding
|
|
- Input: message hash, signature, public key ID
|
|
- Output: verification result
|
|
|
|
- **CRK_RSA_PSS_SIGN**: Generate RSA signature with PSS padding
|
|
- Input: message hash, private key ID
|
|
- Output: RSA signature
|
|
|
|
- **CRK_RSA_PSS_VERIFY**: Verify RSA signature with PSS padding
|
|
- Input: message hash, signature, public key ID
|
|
- Output: verification result
|
|
|
|
Both padding schemes are supported via the cryptokey ioctl interface accessible through ``/dev/crypto``.
|
|
|
|
Key Management Operations
|
|
--------------------------
|
|
|
|
The cryptodev module provides comprehensive key management interfaces:
|
|
|
|
**Key Derivation**
|
|
|
|
- PBKDF2:
|
|
- CRYPTO_PBKDF2_HMAC_SHA1
|
|
- CRYPTO_PBKDF2_HMAC_SHA256
|
|
|
|
**Key Generation**
|
|
|
|
- CRK_GENERATE_AES_KEY: Generate AES key data with specified key ID
|
|
- Supports 128-bit, 192-bit, and 256-bit key generation
|
|
- Generates cryptographically secure random AES keys using software implementation
|
|
- Keys can be used immediately for AES encryption/decryption operations
|
|
|
|
- CRK_GENERATE_RSA_KEY: Generate RSA keypair (public and private) with specified key ID
|
|
- CRK_GENERATE_SECP256R1_KEY: Generate ECDSA keypair on SECP256R1 curve with specified key ID
|
|
- Generates P-256 elliptic curve keypairs for ECDSA operations
|
|
- Uses NuttX's lightweight ECC implementation for key generation
|
|
- Generated keys can be used for ECDSA digital signature operations
|
|
|
|
**Key Lifecycle Management**
|
|
|
|
- CRK_DELETE_KEY: Remove key with specified key ID from the driver
|
|
- CRK_SAVE_KEY: Persist key data to FLASH storage for non-volatile storage
|
|
- CRK_LOAD_KEY: Load previously saved key data from FLASH into RAM
|
|
|
|
**MTD-based Key Storage**
|
|
|
|
NuttX supports persistent key storage using MTD (Memory Technology Device):
|
|
|
|
- Keys can be saved to MTD-based storage for non-volatile persistence
|
|
- Software-based key management (swkey) provides transparent MTD integration
|
|
- Keys are automatically loaded from MTD upon system initialization
|
|
- Supports both symmetric (AES) and asymmetric (RSA, ECC) key storage
|
|
- Enables secure device configuration and credential persistence across reboots
|
|
|
|
**Cryptographic Operations Using Keys**
|
|
|
|
Once keys are allocated, generated, or imported, they can be used for:
|
|
|
|
- Symmetric encryption/decryption operations (AES)
|
|
- RSA signature generation and verification
|
|
- ECDSA digital signature operations
|
|
- Key exchange protocols
|