# Botan

# Hardware Acceleration

Botan provides built-in support for hardware acceleration of certain algorithms on certain platforms. These alternate implementations use special CPU instructions that are not available on all platforms and either speed up the algorithm or improve security in terms of side channel resistance.

The following sections list the platforms and algorithms for which hardware acceleration is available. If the CPU specific optimizations are available at runtime, they are automatically used if enabled in the build. If not, the base implementation is used.

It is possible to disable CPU-specific optimizations at runtime by setting the environment variable `BOTAN_CLEAR_CPUID`. For example `BOTAN_CLEAR_CPUID=avx2` will disable use of any AVX2 instructions.

## x86

On x86-64 and x86-32 platforms, the following CPU specific optimizations are available.

Note

AVX-512 codepaths are only used on x86-64 processors that support AVX-512 extensions similar to Intel Ice Lake or AMD Zen4 (requires AVX-512 F, VL, BW, DQ, VBMI, VBMI2, BITALG, IFMA)

Algorithm | Extension | Module | Added in
--- | --- | --- | ---
AES | VAES-AVX2 AES-NI SSSE3 | `aes_vaes` `aes_ni` `aes_vperm` | 3.6.0 1.9.3 1.9.10
AES-GCM | AVX-512 + CLMUL CLMUL SSSE3 | `ghash_avx512_clmul` `ghash_cpu` `ghash_vperm` | 3.11.0 1.11.6 1.9.10
Argon2 | AVX-512 AVX2 SSSE3 | `argon2_avx512` `argon2_avx2` `argon2_simd64` | 3.11.1 3.0.0 2.19.2
ARIA | AVX-512 + GFNI AES-NI | `aria_avx512_gfni` `aria_hwaes` | 3.11.0 3.11.1
Camellia | AVX-512 + GFNI AVX2 + GFNI AES-NI | `camellia_avx512_gfni` `camellia_avx2_gfni` `camellia_hwaes` | 3.11.0 3.9.0 3.11.1
ChaCha | AVX-512 AVX2 SSSE3 | `chacha_avx512` `chacha_avx2` `chacha_simd32` | 3.1.0 2.8.0 1.11.32
CTR | AVX2 SSSE3 | `ctr_avx2` `ctr_simd32` | 3.11.1 3.11.1
IDEA | AVX2 SSE2 | `idea_avx2` `idea_sse2` | 3.11.0 1.9.4
NOEKEON | SSSE3 | `noekeon_simd` | 1.9.4
Poly1305 | AVX-512 AVX2 | `poly1305_avx512` `poly1305_avx2` | 3.11.0 3.11.0
RDRAND | RDRAND | `processor_rng` | 1.11.31
RDSEED | RDSEED | `rdseed` | 1.11.36
SEED | AVX-512 + GFNI AES-NI | `seed_avx512_gfni` `seed_hwaes` | 3.11.1 3.11.1
Serpent | AVX-512 AVX2 SSSE3 | `serpent_avx512` `serpent_avx2` `serpent_simd` | 3.1.0 2.8.0 1.9.0
SHACAL2 | Intel SHA Extensions AVX-512 AVX2 | `shacal2_x86` `shacal2_avx512` `shacal2_avx2` | 2.3.0 3.9.0 2.13.0
SHA-1 | Intel SHA Extensions AVX2 + BMI2 SSSE3 | `sha1_x86` `sha1_avx2` `sha1_simd` | 2.2.0 3.9.0 1.7.12
SHA-256 | Intel SHA Extensions AVX2 + BMI2 SSSE3 | `sha2_32_x86` `sha2_32_avx2` `sha2_32_simd` | 2.2.0 3.8.0 3.8.0
SHA-512 | Intel SHA Extensions AVX-512 + BMI2 AVX2 + BMI2 | `sha2_64_x86` `sha2_64_avx512` `sha2_64_avx2` | 3.8.0 3.8.0 3.8.0
SHA-3 / SHAKE / KMAC | BMI2 AVX-512 | `keccak_perm_bmi2` `keccak_perm_avx512` | 2.10.0 3.11.0
SM3 | AVX2 + BMI2 SM3-NI | `sm3_avx2_bmi2` `sm3_x86` | 3.11.0 3.11.0
SM4 | AVX-512 + GFNI AVX2 + GFNI SM4-NI AES-NI | `sm4_avx512` `sm4_gfni` `sm4_x86` `sm4_hwaes` | 3.11.0 3.6.0 3.8.0 3.11.1
Twofish | AVX-512 + GFNI | `twofish_avx512` | 3.11.1
Whirlpool | AVX-512 AVX2 | `whirlpool_avx512` `whirlpool_avx2` | 3.11.1 3.11.1
XTS | AVX-512 + CLMUL | `xts_avx512_clmul` | 3.11.0
ZFEC | SSSE3 | `zfec_vperm` | 3.0.0

## ARM

On ARM platforms, the following CPU specific optimizations are available.

Note

The ARMv8 cryptography extensions are only used on 64-bit aarch64 systems

Algorithm | Extension | Module | Added in
--- | --- | --- | ---
AES | ARMv8 Cryptography Extensions NEON | `aes_armv8` `aes_vperm` | 2.3.0 2.12.0
AES-GCM | ARMv8 Cryptography Extensions | `ghash_cpu` | 2.3.0
ARIA | ARMv8 Cryptography Extensions | `aria_hwaes` | 3.11.1
Camellia | ARMv8 Cryptography Extensions | `camellia_hwaes` | 3.11.1
ChaCha | NEON | `chacha_simd32` | 2.8.0
NOEKEON | NEON | `noekeon_simd` | 1.9.4
SEED | ARMv8 Cryptography Extensions | `seed_hwaes` | 3.11.1
Serpent | NEON | `serpent_simd` | 1.9.2
SHACAL2 | NEON ARMv8 Cryptography Extensions | `shacal2_simd` `shacal2_armv8` | 2.3.0 2.13.0
SHA-1 | ARMv8 Cryptography Extensions NEON | `sha1_armv8` `sha1_simd` | 2.2.0 3.8.0
SHA-256 | ARMv8 Cryptography Extensions NEON | `sha2_32_armv8` `sha2_32_simd` | 2.2.0 3.8.0
SHA-384 | ARMv8 Cryptography Extensions | `sha2_64_armv8` | 3.3.0
SHA-512 | ARMv8 Cryptography Extensions | `sha2_64_armv8` | 3.3.0
SM3 | ARMv8 Cryptography Extensions | `sm3_armv8` | 3.11.0
SM4 | ARMv8 Cryptography Extensions ARMv8 Cryptography Extensions | `sm4_armv8` `sm4_hwaes` | 2.8.0 3.11.1
ZFEC | NEON | `zfec_vperm` | 3.0.0

## POWER/PowerPC

On 64-bit POWER/PowerPC platforms, the following CPU specific optimizations are available:

Algorithm | Extension | Module | Added in
--- | --- | --- | ---
AES | POWER8/POWER9 AltiVec | `aes_power8` `aes_vperm` | 2.14.0 2.12.0
ChaCha | AltiVec | `chacha_simd32` | 2.8.0
DARN | POWER9 | `processor_rng` | 2.15.0
Serpent | AltiVec | `serpent_simd` | 1.9.2
SHACAL2 | AltiVec | `shacal2_simd` | 2.3.0
NOEKEON | AltiVec | `noekeon_simd` | 1.9.4

## Loongarch64

On loongarch64, the LSX extensions are used.

Note

Loongarch64 apparently supports a “crypto” extension, for which hwcaps exist for Linux, and there are shipping processors which do support these extensions. However no documentation has been so far located. If you are aware of any such documentation please do contact the maintainers.

Algorithm | Extension | Module | Added in
--- | --- | --- | ---
AES | LSX | `aes_vperm` | 3.8.0
ChaCha | LSX | `chacha_simd32` | 3.8.0
Serpent | LSX | `serpent_simd` | 3.8.0
SHA-1 | LSX | `sha1_simd` | 3.8.0
SHACAL2 | LSX | `shacal2_simd` | 3.8.0
NOEKEON | LSX | `noekeon_simd` | 3.8.0
ZFEC | LSX | `zfec_vperm` | 3.8.0

## Wasm

On Wasm, the SIMD128 extension is used.

Note

To make use of SIMD128, ```simd128` compilation flag is required.

Algorithm | Extension | Module | Added in
--- | --- | --- | ---
AES | SIMD128 | `aes_vperm` | 3.11.0
AES-GCM | SIMD128 | `ghash_vperm` | 3.11.0
Argon2 | SIMD128 | `argon2_simd64` | 3.11.0
ChaCha | SIMD128 | `chacha_simd32` | 3.11.0
Serpent | SIMD128 | `serpent_simd` | 3.11.0
SHA-1 | SIMD128 | `sha1_simd` | 3.11.0
SHA-256 | SIMD128 | `sha2_32_simd` | 3.11.0
SHACAL2 | SIMD128 | `shacal2_simd` | 3.11.0
NOEKEON | SIMD128 | `noekeon_simd` | 3.11.0
ZFEC | SIMD128 | `zfec_vperm` | 3.11.0

## Configuring Acceleration

If it is desirable to avoid using some form of acceleration, this can be accomplished at build time by using `--disable-modules=`. For instance, to remove support of ARMv8 intrinsics for AES, use `--disable-modules=aes_armv8`. Note that this is rarely if ever required; if support for the CPU extension is not available at runtime then the code using that extension will simply be skipped over. The only reason to do this is when the code is being deployed to a fixed target (eg the specific board used in your product) and you know that target does not support such an extension, and you wish to minimize code size.

It is also possible to disable acceleration at runtime using `BOTAN_CLEAR_CPUID` environment variable. This is the preferred mode of disabling acceleration.