1# Feature and Optimization Configuration Guide 2 3openHiTLS has a highly modular architecture, with RAM/ROM size depending on the selected features and optimization configurations. 4 5## 1. Feature Configuration 6The [feature.json](../../../config/json/feature.json) file defines the features of openHiTLS. It serves both as a comprehensive, full-featured configuration file and as a feature dictionary for user reference. It contains two parts: libs and modules, where the libs section defines the components and features of openHiTLS. 7 8Here's a simple introduction to the rules for component and feature configuration in the json file: 9 10```json 11"libs":{ // Components 12 "hitls_crypto":{ // Component name, also a feature name 13 "features":{ // Feature definition 14 "c":{ // C language implementation features 15 "md": { // Feature name 16 "sha1": null, // md sub-feature 17 "sha2": { // md sub-feature 18 "sha224": null, // sha2 sub-feature 19 "sha256": null, // sha2 sub-feature 20 ... 21 }, 22 }, 23 "kdf": { 24 "scrypt": { 25 "deps": ["sha256", "pbkdf2"] // Features required by scrypt 26 }, 27 "hkdf": null, 28 "deps": ["hmac"] // Features required by kdf, inherited by kdf sub-features 29 }, 30 "hpke": { 31 "deps": ["hkdf"], 32 "opts": [ 33 ["aes", "chacha20"], // hpke first group of optional dependencies 34 ["ecc", "x25519"] // hpke second group of optional dependencies 35 ] 36 } 37 }, 38 "asm": { 39 "x8664": { 40 "sha1": {"ins_set":["x8664", "avx512"]}, 41 "sha2": {"ins_set":["x8664", "avx512"]} 42 }, 43 "armv8": { 44 "sha1": null, 45 "sha2": null 46 } 47 } 48 } 49 }, 50 "hitls_tls": {...}, 51 "hitls_pki": {...}, 52 ... 53} 54``` 55 56Field description: 57|Field Name|Type|Required|Default|Description| 58|---|---|---|---|---| 59|libs|object|Yes|None|Component definition, component name is also feature name| 60|features|object|Yes|None|Feature definition| 61|c|object|No|None|C language implementation features| 62|feature or sub-feature|object|No|None|Feature| 63|deps|array|No|None|Features required by a feature, all features in this list are mandatory<br>Sub-features inherit dependencies from main features<br>No need to enable explicitly, build framework will automatically enable required features| 64|opts|array|No|None|Optional features, at least one feature from this list must be selected<br>Sub-features inherit optional dependencies from main features<br>Need to enable explicitly| 65|asm|object|No|None|Assembly language implementation features| 66|ins_set|array|No|None|Instruction sets supported by a feature| 67 68Feature configuration examples: 691. Enable hpke algorithm: `python3 configure.py --enable eal hpke aes gcm x25519` 70 - Features to enable explicitly: 71 - Algorithm upper layer feature: eal 72 - Main feature: hpke 73 - Dependencies: 74 - aes, gcm: first group of hpke optional dependencies 75 - x25519: second group of hpke optional dependencies 76 - Features enabled by default: Build framework will automatically enable direct and indirect dependencies 77 - hkdf: required by hpke 78 - hmac: required by hkdf 79 802. Use tls13 protocol with tls13_aes_128_gcm_sha256 suite: `python3 configure.py --enable proto proto_tls13 suite_aes_128_gcm_sha256 ...` 81 - Features to enable explicitly: 82 - Protocol: proto 83 - Protocol version: proto_tls13 84 - Algorithm suite: tls13_aes_128_gcm_sha256 85 - Features enabled by default: Build framework will automatically enable direct and indirect dependencies 86 - tlv, sal, eal, list: required by proto 87 - sha256, gcm, aes, ecdh: required by suite_aes_128_gcm_sha256 88 - Others 89 90## 2. Optimization Configuration 91 92### Configuration Categories 93 94#### System-Related Configuration 95|Configuration|Description|Recommendation| 96|---|---|---| 97|HITLS_BIG_ENDIAN|Indicates system uses big-endian byte order. Affects data storage and transmission format. If not specified, little-endian is used by default.|Enable if system is big-endian| 98|HITLS_BSL_SAL_LINUX|Use Linux system abstraction layer. Used to adapt Linux system calls.|Enable if supported, otherwise disable| 99|HITLS_CRYPTO_NO_AUXVAL|Do not use auxiliary vector to get CPU features. Requires alternative methods for CPU feature detection.|Enable if supported, otherwise disable| 100|HITLS_CRYPTO_ASM_CHECK|Enable assembly code checking. Checks at runtime if CPU supports corresponding instruction set extensions. Currently supported algorithm checks include: aes, sm4, gcm, md5, sha1, sha2, sm3, ecc.|Only effective when ealinit feature is enabled| 101 102#### Big Number Configuration 103|Configuration|Description|Recommendation| 104|---|---|---| 105|HITLS_SIXTY_FOUR_BITS|Indicates system is 64-bit platform.|Enable if system is 64-bit| 106|HITLS_THIRTY_TWO_BITS|Indicates system is 32-bit platform.|Enable if system is 32-bit| 107 108#### Key Generation Optimization Configuration 109|Configuration|Description|Recommendation| 110|---|---|---| 111|CRYPT_DH_TRY_CNT_MAX|Maximum number of attempts for DH key pair generation, default 100. When the generated key does not meet requirements, it will be regenerated until reaching this limit.|Keep default value of 100 unless there are special performance requirements| 112|CRYPT_DSA_TRY_MAX_CNT|Maximum number of attempts for DSA key pair generation, default 100. When the generated key does not meet requirements, it will be regenerated until reaching this limit.|Keep default value of 100 unless there are special performance requirements| 113|CRYPT_ECC_TRY_MAX_CNT|Maximum number of attempts for ECC key pair generation, default 100. When the generated key does not meet requirements, it will be regenerated until reaching this limit.|Keep default value of 100 unless there are special performance requirements| 114 115#### ECC Optimization Configuration 116|Configuration|Description|Recommendation| 117|---|---|---| 118|HITLS_CRYPTO_NIST_ECC_ACCELERATE|Use hardware acceleration for NIST curves. Enabled by default, configured in config/json/compile.json. This acceleration depends on INT128; if system doesn't support it, this configuration is ignored.|Enabled by default| 119 120#### Random Number Generation Configuration 121|Configuration|Description|Recommendation| 122|---|---|---| 123|DRBG_MAX_RESEED_INTERVAL|Maximum interval for DRBG (Deterministic Random Bit Generator) reseeding, default 10000. After generating 10000 random numbers, entropy source must be reacquired for reseeding.|Keep default value of 10000. Larger values reduce random number security, smaller values affect performance| 124|ENTROPY_USE_DEVRANDOM|Use operating system device random number as entropy source. On Linux systems, typically uses /dev/random or /dev/urandom.|Enable if supported| 125|HITLS_CRYPTO_INIT_RAND_ALG|Initialization random number algorithm for DRBG.|Default value is CRYPT_RAND_SHA256, optional values refer to CRYPT_RAND_AlgId in header file include/crypto/crypt_algid.h| 126 127#### Other Configuration 128|Configuration|Description|Recommendation| 129|---|---|---| 130|HITLS_BSL_LOG_NO_FORMAT_STRING|Log output without format strings, directly outputs raw strings. Can improve logging performance. This feature is mainly used in the protocol module.|Enable if log viewing is not needed| 131|HITLS_EAL_INIT_OPTS=n|EAL initialization options. Default value is 0, indicating EAL initialization is disabled.<br>When HITLS_EAL_INIT_OPTS is defined, CRYPT_EAL_Init and CRYPT_EAL_Cleanup will be marked as constructor and destructor functions, and will override the parameters of these two functions.<br>Different values can be set to enable different EAL initializations:<br>- CPU feature detection: CRYPT_EAL_INIT_CPU 0x01<br>- Error code module initialization: CRYPT_EAL_INIT_BSL 0x02<br>- Random number initialization: CRYPT_EAL_INIT_RAND 0x04<br>- Provider initialization: CRYPT_EAL_INIT_PROVIDER 0x08<br>The value of n is the sum of the above values|Enable based on requirements| 132 133### Configuration Method 134 135Refer to 1_Build and Installation Guide, use --add_options to add configurations or --del_options to delete default configurations. 136 137Example: 138```bash 139python3 ../configure.py --add_options="-DHITLS_CRYPTO_ASM_CHECK" --del_options="-DHITLS_CRYPTO_NIST_ECC_ACCELERATE" 140 141python3 ../configure.py --add_options="-DHITLS_BSL_SAL_LINUX" # Same as python3 ../configure.py --system linux 142 143python3 ../configure.py --add_options="-DHITLS_THIRTY_TWO_BITS" # Same as python3 ../configure.py --bits 32 144 145python3 ../configure.py --add_options="-DHITLS_EAL_INIT_OPTS=9" # 9 = CRYPT_EAL_INIT_CPU + CRYPT_EAL_INIT_PROVIDER 146``` 147