# amd/aocl-crypto architecture

> Architecture diagram of the GitHub repository amd/aocl-crypto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amd/aocl-crypto
- Repository: https://github.com/amd/aocl-crypto

## Overview

AOCL-Cryptography is a Zen-optimized cryptographic library exposing C APIs for symmetric encryption, hashes, MACs, random generation, ECDH, and RSA. Callers configure and invoke those APIs; the library provides algorithm implementations and, for some algorithms, architecture-specific kernels. The tree also includes an optional OpenSSL provider integration. Edges are limited to README-documented capabilities and relationships visible in sampled files or the source index; unsampled subsystem wiring is left out or marked unverified.

Main entry points: [`lib/digest/sha3.cc`](https://github.com/amd/aocl-crypto/blob/main/lib/digest/sha3.cc) (Digest implementations), [`include/alcp/alcp.h`](https://github.com/amd/aocl-crypto/blob/main/include/alcp/alcp.h) (C API surface), [`lib/rsa/builder.cc`](https://github.com/amd/aocl-crypto/blob/main/lib/rsa/builder.cc) (RSA dispatch builder), [`lib/rsa/rsa.cc`](https://github.com/amd/aocl-crypto/blob/main/lib/rsa/rsa.cc) (RSA operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public APIs"]
  node_public_api["C API surface<br/>[alcp.h]"]
  node_cipher_api["Cipher API<br/>[cipher.h]"]
  node_digest_api["Digest API<br/>[digest.h]"]
  node_mac_api["MAC API<br/>[mac.h]"]
  node_rsa_api["RSA API<br/>[rsa.h]"]
  node_cipher_c["Cipher C bindings<br/>[c_cipher.cc]"]
  node_digest_c["Digest C bindings<br/>[c_digest.cc]"]
  node_rsa_c["RSA C bindings<br/>[c_rsa.cc]"]
end

subgraph group_symmetric["Symmetric Cryptography"]
  node_cipher_engine["AES implementation<br/>[aes_generic.cc]"]
  node_aead_engine["AEAD ciphers<br/>[aes_gcm.cc]"]
end

subgraph group_hashmac["Hashes and MACs"]
  node_digest_engine["Digest implementations<br/>[sha3.cc]"]
  node_mac_engine["MAC implementations<br/>[cmac.cc]"]
  node_hmac_batch["Multibuffer HMAC<br/>[hmac_mb.cc]"]
  node_rng_engine["Random generation<br/>[builder.cc]"]
end

subgraph group_asymmetric["Public-Key Cryptography"]
  node_ecdh_engine["ECDH<br/>[ecdh_x25519.cc]"]
  node_rsa_builder["RSA dispatch builder<br/>[builder.cc]"]
  node_rsa_engine["RSA operations<br/>[rsa.cc]"]
  node_rsa_zen4["Zen 4 RSA kernel<br/>[rsa.cc]"]
end

subgraph group_integrations["Compatibility Integrations"]
  node_openssl_provider["OpenSSL provider<br/>[alcp_provider.c]"]
end

node_caller(("Library caller"))

node_caller -->|"uses"| node_public_api
node_public_api -.->|"exposes"| node_cipher_api
node_caller -->|"configures ciphers"| node_cipher_api
node_caller -->|"requests hashes"| node_digest_api
node_caller -->|"requests MACs"| node_mac_api
node_caller -->|"requests RSA"| node_rsa_api
node_cipher_c -->|"uses"| node_cipher_engine
node_digest_c -.->|"dispatches"| node_digest_engine
node_digest_engine -->|"selects kernels"| node_digest_engine
node_hmac_batch -.->|"uses digest"| node_digest_engine
node_caller -->|"requests random bytes"| node_rng_engine
node_caller -->|"derives shared keys"| node_ecdh_engine
node_rsa_c -->|"uses builder"| node_rsa_builder
node_rsa_builder -.->|"dispatches to"| node_rsa_engine
node_rsa_engine -.->|"selects kernel"| node_rsa_zen4
node_openssl_provider -.->|"uses RSA API"| node_rsa_api

click node_public_api "https://github.com/amd/aocl-crypto/blob/main/include/alcp/alcp.h"
click node_cipher_api "https://github.com/amd/aocl-crypto/blob/main/include/alcp/cipher.h"
click node_digest_api "https://github.com/amd/aocl-crypto/blob/main/include/alcp/digest.h"
click node_mac_api "https://github.com/amd/aocl-crypto/blob/main/include/alcp/mac.h"
click node_rsa_api "https://github.com/amd/aocl-crypto/blob/main/include/alcp/rsa.h"
click node_cipher_c "https://github.com/amd/aocl-crypto/blob/main/lib/capi/c_cipher.cc"
click node_cipher_engine "https://github.com/amd/aocl-crypto/blob/main/lib/cipher/aes_generic.cc"
click node_aead_engine "https://github.com/amd/aocl-crypto/blob/main/lib/cipher/aes_gcm.cc"
click node_digest_c "https://github.com/amd/aocl-crypto/blob/main/lib/capi/c_digest.cc"
click node_digest_engine "https://github.com/amd/aocl-crypto/blob/main/lib/digest/sha3.cc"
click node_mac_engine "https://github.com/amd/aocl-crypto/blob/main/lib/mac/cmac.cc"
click node_hmac_batch "https://github.com/amd/aocl-crypto/blob/main/lib/mac/hmac_mb.cc"
click node_rng_engine "https://github.com/amd/aocl-crypto/blob/main/lib/rng/builder.cc"
click node_ecdh_engine "https://github.com/amd/aocl-crypto/blob/main/lib/ec/ecdh_x25519.cc"
click node_rsa_c "https://github.com/amd/aocl-crypto/blob/main/lib/capi/c_rsa.cc"
click node_rsa_builder "https://github.com/amd/aocl-crypto/blob/main/lib/rsa/builder.cc"
click node_rsa_engine "https://github.com/amd/aocl-crypto/blob/main/lib/rsa/rsa.cc"
click node_rsa_zen4 "https://github.com/amd/aocl-crypto/blob/main/lib/arch/zen4/rsa.cc"
click node_openssl_provider "https://github.com/amd/aocl-crypto/blob/main/lib/compat/openssl/provider/alcp_provider.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_cipher_api,node_digest_api,node_mac_api,node_rsa_api,node_cipher_c,node_digest_c,node_rsa_c toneBlue
class node_cipher_engine,node_aead_engine toneAmber
class node_digest_engine,node_mac_engine,node_hmac_batch,node_rng_engine toneMint
class node_ecdh_engine,node_rsa_builder,node_rsa_engine,node_rsa_zen4 toneRose
class node_openssl_provider,node_caller toneIndigo
```

## Components

### Public APIs

- [C API surface](https://github.com/amd/aocl-crypto/blob/main/include/alcp/alcp.h): `include/alcp/alcp.h`
- [Cipher API](https://github.com/amd/aocl-crypto/blob/main/include/alcp/cipher.h): `include/alcp/cipher.h`
- [Digest API](https://github.com/amd/aocl-crypto/blob/main/include/alcp/digest.h): `include/alcp/digest.h`
- [MAC API](https://github.com/amd/aocl-crypto/blob/main/include/alcp/mac.h): `include/alcp/mac.h`
- [RSA API](https://github.com/amd/aocl-crypto/blob/main/include/alcp/rsa.h): `include/alcp/rsa.h`
- [Cipher C bindings](https://github.com/amd/aocl-crypto/blob/main/lib/capi/c_cipher.cc): `lib/capi/c_cipher.cc`
- [Digest C bindings](https://github.com/amd/aocl-crypto/blob/main/lib/capi/c_digest.cc): `lib/capi/c_digest.cc`
- [RSA C bindings](https://github.com/amd/aocl-crypto/blob/main/lib/capi/c_rsa.cc): `lib/capi/c_rsa.cc`

### Symmetric Cryptography

- [AES implementation](https://github.com/amd/aocl-crypto/blob/main/lib/cipher/aes_generic.cc): `lib/cipher/aes_generic.cc`
- [AEAD ciphers](https://github.com/amd/aocl-crypto/blob/main/lib/cipher/aes_gcm.cc): `lib/cipher/aes_gcm.cc`

### Hashes and MACs

- [Digest implementations](https://github.com/amd/aocl-crypto/blob/main/lib/digest/sha3.cc): `lib/digest/sha3.cc`
- [MAC implementations](https://github.com/amd/aocl-crypto/blob/main/lib/mac/cmac.cc): `lib/mac/cmac.cc`
- [Multibuffer HMAC](https://github.com/amd/aocl-crypto/blob/main/lib/mac/hmac_mb.cc): `lib/mac/hmac_mb.cc`
- [Random generation](https://github.com/amd/aocl-crypto/blob/main/lib/rng/builder.cc): `lib/rng/builder.cc`

### Public-Key Cryptography

- [ECDH](https://github.com/amd/aocl-crypto/blob/main/lib/ec/ecdh_x25519.cc): `lib/ec/ecdh_x25519.cc`
- [RSA dispatch builder](https://github.com/amd/aocl-crypto/blob/main/lib/rsa/builder.cc): `lib/rsa/builder.cc`
- [RSA operations](https://github.com/amd/aocl-crypto/blob/main/lib/rsa/rsa.cc): `lib/rsa/rsa.cc`
- [Zen 4 RSA kernel](https://github.com/amd/aocl-crypto/blob/main/lib/arch/zen4/rsa.cc): `lib/arch/zen4/rsa.cc`

### Compatibility Integrations

- [OpenSSL provider](https://github.com/amd/aocl-crypto/blob/main/lib/compat/openssl/provider/alcp_provider.c): `lib/compat/openssl/provider/alcp_provider.c`

### Other components

- **Library caller**

## Connections

- Library caller → C API surface: uses (evidence: `README.md`)
- C API surface → Cipher API: exposes
- Library caller → Cipher API: configures ciphers (evidence: `README.md`)
- Library caller → Digest API: requests hashes (evidence: `README.md`)
- Library caller → MAC API: requests MACs (evidence: `README.md`)
- Library caller → RSA API: requests RSA (evidence: `README.md`)
- Cipher C bindings → AES implementation: uses (evidence: `lib/capi/c_cipher.cc`)
- Digest C bindings → Digest implementations: dispatches
- Digest implementations → Digest implementations: selects kernels (evidence: `lib/digest/sha3.cc`)
- Multibuffer HMAC → Digest implementations: uses digest
- Library caller → Random generation: requests random bytes (evidence: `README.md`)
- Library caller → ECDH: derives shared keys (evidence: `README.md`)
- RSA C bindings → RSA dispatch builder: uses builder (evidence: `lib/capi/c_rsa.cc`)
- RSA dispatch builder → RSA operations: dispatches to
- RSA operations → Zen 4 RSA kernel: selects kernel
- OpenSSL provider → RSA API: uses RSA API
