docs: refactor security API and consolidate external/ docs#533
Merged
tanghao-xiaomi merged 1 commit intoMay 9, 2026
Merged
Conversation
tanghao-xiaomi
requested review from
TangMeng12,
aiduxiaoxiong,
smile0425 and
yanxingyu17
as code owners
Collaborator
Author
|
/check-cla |
✅ CLA Verification Complete@tanghao-xiaomi All contributors have signed the CLA!
📋 View detailed check results: Action Run #25553987994 Your pull request can now proceed with the review process! 🎉 |
tanghao-xiaomi
force-pushed
the
refactor-security-api
branch
from
bf4052c to
7081bf1
Compare
tanghao-xiaomi
changed the title
Collaborator
Author
|
/check-cla |
✅ CLA Verification Complete@tanghao-xiaomi All contributors have signed the CLA!
📋 View detailed check results: Action Run #25556114057 Your pull request can now proceed with the review process! 🎉 |
Bring security.md in line with the openvela API documentation standard
and cover the full public surface of the security framework. Also
consolidate the small docs/doxygen/api/external/ directory back into
framework/ so that API references live in one coherent tree.
== Security framework ==
Structure changes:
- Remove all Chinese/Arabic numeric prefixes from headings ('一、',
'二、', '1、', etc.)
- Flatten the three-level '## > ### > ####' nesting in favor of the
standard '## group > ### api' layout
- Add '## openvela 实现说明' section (REE/TEE split, rpmsg channel,
API layering, rootkey flow)
- Add header include declaration
CA application-layer APIs (24 in 5 groups) rewritten as individual
'### function' entries, each with signature, Chinese description,
**参数** list and **返回值** section:
- Secure Storage (SST): 5 APIs from comsst_ca_api.h
- Triad (DID + Key): 5 APIs from triad_ca_api.h
- WeChat Pay CA: 4 APIs from wxcodepay_ca_api.h
- Alipay CA: 4 APIs from alipay_ca_api.h
- PIN CA: 6 APIs from pin_ca_api.h
MiTEE Rootkey section rewritten with proper signature blocks and
parameter descriptions for the read (boardctl BOARDIOC_UNIQUEKEY) and
write (rootkey_provision) flows.
GP TEE Client API:
- Clean up signatures (remove embedded Doxygen-style comment blocks
that were inconsistent with the rest of the document)
- Translate all parameter and return-value descriptions to Chinese
- Add two missing public APIs: TEEC_RegisterSharedMemory and
TEEC_RequestCancellation
- Coverage: 9 / 9 against OP-TEE <tee_client_api.h>
GP TEE Internal API:
- Keep the status-reference table format (openvela implementation
status vs. GP specification), but add an opening paragraph that
points readers to the GlobalPlatform TEE Internal Core API
Specification v1.3.1 and <tee_internal_api.h> for authoritative
signature and semantics
- Clarify the meaning of the '支持' and '实现不完整' status labels
Every CA and TEEC signature in the document has been verified against
the corresponding source header.
== Android Keystore API (new section) ==
Merge the contents previously hosted in docs/doxygen/api/external/
security/keystore_client.md into security.md as a new top-level
'## Android Keystore Client API' section. Rationale: the keystore
client is openvela's second security scheme alongside MiTEE TEE, so
documenting both in one file gives developers a single entry point.
The new section covers the 5 public C APIs from
external/android/system/security/keystore/include/keystore/client.h
(keyStoreInsert / Get / Del / Exist / Reset) and the full KEYSTORE_*
error-code table. The '## openvela 实现说明' paragraph is updated to
explain the dual-scheme architecture.
== external/ directory consolidation ==
Delete docs/doxygen/api/external/ entirely (4 files: ffmpeg.md,
index.md, security/index.md, security/keystore_client.md). The
directory only contained two substantive docs, and both have been
moved to a more natural home:
- keystore_client.md → framework/security.md (new top-level section)
- ffmpeg.md integration notes (Kconfig + LGPL compliance) →
framework/media/index.md 'openvela 实现说明' section. FFmpeg's
native API docs themselves are not replicated, readers are linked
to the upstream FFmpeg documentation as the authoritative source.
Update api/index.md to remove the '第三方开源库' entry accordingly.
tanghao-xiaomi
force-pushed
the
refactor-security-api
branch
from
7081bf1 to
c034416
Compare
Collaborator
Author
|
/check-cla |
✅ CLA Verification Complete@tanghao-xiaomi All contributors have signed the CLA!
📋 View detailed check results: Action Run #25556537358 Your pull request can now proceed with the review process! 🎉 |
TangMeng12
approved these changes
May 8, 2026
TangMeng12
approved these changes
May 8, 2026
aiduxiaoxiong
approved these changes
May 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bring
docs/doxygen/api/framework/security.mdin line with the openvela API documentation standard and cover the full public surface of the security framework. Also consolidate the tinydocs/doxygen/api/external/tree back intoframework/so that API references live in one coherent place.Changes
Security framework (
framework/security.md)Structure: remove numeric chapter prefixes (
一、,1、…), flatten the## > ### > ####nesting into the standard## group → ### apilayout, add## openvela 实现说明section, add header include declaration.CA application-layer APIs (24 APIs, 5 groups) rewritten as individual
### functionentries with Chinese parameter / return-value descriptions:MiTEE Rootkey: rewritten with proper signature blocks for the read (
boardctl BOARDIOC_UNIQUEKEY) and write (rootkey_provision) flows.GP TEE Client API: cleaned up signatures, translated descriptions to Chinese, added two missing public APIs (
TEEC_RegisterSharedMemory,TEEC_RequestCancellation). Coverage: 9 / 9 against OP-TEE<tee_client_api.h>.GP TEE Internal API: keeps the status-reference table format but adds an opening paragraph pointing readers to the GlobalPlatform TEE Internal Core API Specification v1.3.1 as the authoritative source.
Android Keystore API (merged in)
Moved the contents previously at
docs/doxygen/api/external/security/keystore_client.mdintosecurity.mdas a new top-level## Android Keystore Client APIsection. Rationale: the Android Keystore client is openvela's second security scheme alongside MiTEE TEE — documenting both in one file gives developers a single entry point.Covers the 5 public C APIs from
external/android/system/security/keystore/include/keystore/client.h(keyStoreInsert/Get/Del/Exist/Reset) and the fullKEYSTORE_*error-code table.external/ directory consolidation
Delete
docs/doxygen/api/external/entirely (4 files). Both substantive docs have been moved to a more natural home:keystore_client.md→framework/security.mdframework/media/index.mdopenvela 实现说明section (FFmpeg's native API is not replicated; readers are linked to the upstream FFmpeg documentation as the authoritative source)api/index.mdis updated to remove the第三方开源库entry.Verification
keyStoreInsert/keyStoreGet/keyStoreDel/keyStoreExist/keyStoreResetKEYSTORE_*error codes coveredexternal/docs remainStats
security.mdlinesexternal/files