DOCA AES-GCM

Par où commencer : Cette compétence suppose que DOCA est déjà installé et que l'utilisateur effectue un travail pratique d'accélération AES-GCM sur un BlueField / ConnectX / hôte avec DOCA. Ouvrez TASKS.md si l'utilisateur veut faire quelque chose (configurer / compiler / modifier / exécuter / tester / déboguer) ; ouvrez CAPABILITIES.md quand la question porte sur ce que DOCA AES-GCM peut exprimer dans cette version. Si l'utilisateur n'a pas encore installé DOCA, dirigez-le d'abord vers doca-setup. Si l'utilisateur se demande « devrais-je vraiment utiliser l'accélérateur pour ce chiffrement ? », la règle de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes est la première étape. Si l'utilisateur traite AES-GCM comme une primitive de confidentialité seule (style AES-CTR / AES-CBC brut), arrêtez-vous et lisez d'abord la note AEAD dans CAPABILITIES.md ## Safety policy — AES-GCM est un chiffrement authentifié, et confondre les deux est le mode de défaillance le plus coûteux que cette compétence existe pour prévenir.

Questions d'exemple auxquelles cette compétence répond bien

Les CLASSES de questions DOCA AES-GCM auxquelles cette compétence est construite pour répondre, chacune avec un exemple travaillé. L'agent doit traiter la classe comme l'élément porteur — l'exemple travaillé est une seule instance.

« Devrais-je décharger ce chiffrement AES-GCM vers DOCA AES-GCM, ou simplement le faire sur le CPU avec OpenSSL ? » — exemple travaillé : « Je chiffre des enregistrements TLS de 4 Kio au débit ; doca-aes-gcm vaut-il la peine de configurer par rapport à OpenSSL EVP_aes_256_gcm sur le CPU ? ». Répondu par le tableau de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes + les points « quand NE PAS utiliser doca-aes-gcm » dans CAPABILITIES.md ## Safety policy.
« Mon appareil supporte-t-il la taille de clé AES-GCM que je veux ? » — exemple travaillé : « AES-256-GCM est-il dans l'accélérateur sur ce BlueField ? Et pendant qu'on y est, AES-192-GCM est-il disponible ? » (Réponse : la bibliothèque n'expose que DOCA_AES_GCM_KEY_128 / DOCA_AES_GCM_KEY_256 ; AES-192 n'est pas dans l'enum et n'est pas supporté. Pour les deux vrais types de clé, vérifiez avec doca_aes_gcm_cap_task_encrypt_is_key_type_supported(devinfo, key_type) et le _decrypt_is_key_type_supported correspondant. AES-192 n'est pas disponible — orientez vers une bibliothèque CPU.) Répondu par les requêtes de capacité par type de clé et les requêtes doca_aes_gcm_cap_task_*_is_supported par tâche dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« Comment déchiffrer correctement un message AES-GCM et vérifier le tag d'authentification ? » — exemple travaillé : « ma complétude de doca_aes_gcm_task_decrypt signale une erreur — la sortie en texte clair est-elle sûre à utiliser ? ». Répondu par la règle de vérification du tag d'authentification dans CAPABILITIES.md ## Safety policy (ne pas utiliser le texte clair si le tag d'authentification ne s'est pas vérifié) + le workflow de gestion des complétudes de déchiffrement dans TASKS.md ## test et TASKS.md ## debug.
« Quelles permissions la source / la destination mmap ont-elles besoin ? » — exemple travaillé : « mon doca_aes_gcm_task_encrypt retourne DOCA_ERROR_NOT_PERMITTED ». Répondu par la matrice de permission dans CAPABILITIES.md ## Safety policy + la checklist de configuration des permissions mmap dans TASKS.md ## test.
« Cette API DOCA AES-GCM est-elle disponible sur ma version DOCA installée ? » — exemple travaillé : « AES-192-GCM est-il dans le DOCA que j'ai installé, sur cet appareil ? ». Répondu par le recouvrement de compatibilité des versions dans CAPABILITIES.md ## Version compatibility, qui fait des renvois croisés vers la chaîne de détection canonique dans doca-version et ajoute les points AES-GCM-spécifiques « découvrir les tailles de clé via requête cap ».
*« Que signifie ce `DOCAERRORd'un appel AES-GCM et quelle couche l'a causé ? »** — exemple travaillé : *«DOCA_ERROR_IO_FAILEDsur la complétude du déchiffrement — s'agit-il d'un bug matériel ou d'une non-concordance de tag ? »*. Répondu par le recouvrement AES-GCM sur la taxonomie cross-library dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) + l'escalade échelonnée dans [TASKS.md ## debug](TASKS.md#debug) qui escalade vers [doca-debug`](../../doca-debug/SKILL.md).

Public

Cette compétence sert les développeurs externes construisant des applications qui consomment la bibliothèque DOCA AES-GCM — c'est-à-dire les utilisateurs dont le code appelle doca_aes_gcm_* (directement en C/C++, ou via FFI/bindings dans un autre langage) pour décharger le chiffrement/déchiffrement authentifié AES-GCM sur un DPU BlueField ou un accélérateur ConnectX. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA AES-GCM lui-même.

Portée linguistique. DOCA AES-GCM est livré en tant que bibliothèque C avec le nom de module pkg-config doca-aes-gcm. Les exemples livrés sont écrits en C. Les consommateurs C et C++ sont le cas canonique et les exemples travaillés dans TASKS.md supposent ce chemin. Les consommateurs d'autres langages (Rust, Go, Python, …) consomment le même *.so via FFI ou des bindings spécifiques au langage ; la contribution de la compétence dans ce cas est de maintenir le cycle de vie, la découverte de capacité, les permissions, la taxonomie d'erreurs, la sémantique AEAD, et les conseils sur chiffrement vs déchiffrement indépendants du langage, et d'orienter l'agent vers l'ABI C public comme surface faisant autorité qu'any wrapper appellera finalement.

La gestion des clés sort du champ d'application. Cette compétence enseigne à l'agent comment utiliser la bibliothèque DOCA AES-GCM ; elle n'enseigne pas à l'utilisateur comment générer, stocker, faire tourner ou distribuer des clés AES-GCM. La gestion des clés est la responsabilité de l'utilisateur (un KMS, un HSM, un fichier scellé, une variable d'env que l'utilisateur fait confiance). La seule règle de gestion des clés de la compétence est celle opérationnelle dans CAPABILITIES.md ## Safety policy : ne pas enregistrer les clés, ne pas les committer dans la source, et traiter tout buffer de clé que le programme détient comme une mémoire sensible.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur effectue un travail pratique DOCA AES-GCM, dans n'importe quel langage. Concrètement :

Initialiser un contexte doca_aes_gcm sur un doca_dev et configurer au moins un type de tâche (doca_aes_gcm_task_encrypt et/ou doca_aes_gcm_task_decrypt) avant doca_ctx_start().
Choisir entre chiffrement (doca_aes_gcm_task_encrypt — prend clé + IV + AAD + texte clair, produit texte chiffré + tag d'authentification) et déchiffrement (doca_aes_gcm_task_decrypt — prend clé + IV + AAD + texte chiffré + tag d'authentification attendu, produit texte clair et vérifie le tag) pour la forme des données de l'utilisateur.
Définir correctement les permissions sur doca_mmap pour le buffer source (DOCA_ACCESS_FLAG_LOCAL_READ_ONLY au minimum — le texte clair au chiffrement ou le texte chiffré au déchiffrement) et le buffer destination (DOCA_ACCESS_FLAG_LOCAL_READ_WRITE).
Vérifier quels types de clé AES-GCM (DOCA_AES_GCM_KEY_128 / DOCA_AES_GCM_KEY_256 — AES-192 n'est pas dans la bibliothèque) l'accélérateur du périphérique actif annonce via doca_aes_gcm_cap_task_encrypt_is_key_type_supported / doca_aes_gcm_cap_task_decrypt_is_key_type_supported, et quels types de tâche via doca_aes_gcm_cap_task_encrypt_is_supported / _task_decrypt_is_supported.
Dimensionner le texte clair par soumission par rapport à doca_aes_gcm_cap_task_encrypt_get_max_buf_size(devinfo).
Valider un aller-retour chiffrement + déchiffrement par rapport à un vecteur de test AES-GCM publié (NIST GCMVS, ou exemples RFC 5288) avant de passer des données utilisateur à l'accélérateur.
Gérer le résultat de vérification du tag d'authentification sur les complétudes de déchiffrement en tant que signal critique pour la sécurité — une complétude de non-concordance de tag signifie que le texte chiffré a été altéré ou corrompu, et la sortie en texte clair de cette tâche est empoisonnée et ne doit pas être consommée.
Déboguer un DOCA_ERROR_* retourné d'un appel AES-GCM (cycle de vie vs. taille de clé non supportée vs. permission vs. échec de vérification de tag au déchiffrement) et l'événement de complétude de tâche sur le moteur de progression.
Concevoir ou étendre des bindings non-C (Rust, Go, Python, …) qui enveloppent l'ABI C AES-GCM — pour le cycle de vie, la permission, la capacité, la sémantique AEAD, et les règles chiffrement vs. déchiffrement que le wrapper doit respecter.

Ne chargez pas cette compétence pour l'orientation générale de DOCA, l'installation de DOCA lui-même, les modes AES qui ne sont pas GCM (CBC / CTR / XTS — ceux ne sont pas dans cette bibliothèque et CPU + OpenSSL est la bonne réponse), le hachage SHA sur la même famille d'accélérateurs (utilisez doca-sha), ou d'autres bibliothèques DOCA. Pour ceux-ci, utilisez doca-public-knowledge-map.

Ce que cette compétence fournit

Ceci est un chargeur léger. Le corps ne garde que l'orientation nécessaire pour choisir le bon fichier suivant. Le matériel substantiel spécifique à AES-GCM vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que DOCA AES-GCM peut exprimer dans cette version : les deux types de tâche (chiffrement et déchiffrement), la forme de sortie AEAD (texte chiffré + tag d'authentification au chiffrement ; texte clair vérifié au déchiffrement), la surface de type de clé AES-GCM (seulement 128-bit et 256-bit — AES-192 n'est pas dans l'enum, les deux cap-queried), la surface de requête de capacité (doca_aes_gcm_cap_* pour la présence de tâche, le support du type de clé, et le dimensionnement du buffer), la taxonomie d'erreurs AES-GCM (mappée sur l'ensemble cross-library DOCA_ERROR_*, avec traitement explicite du résultat d'échec de vérification de tag comme critique pour la sécurité), la surface d'observabilité (événements de complétude par tâche sur le moteur de progression), la politique de sécurité qui limite les décisions de permission mmap source / destination et les mises en garde de gestion des clés, et la règle de sélection de chemin (quand utiliser doca-aes-gcm par rapport à CPU OpenSSL ou une autre bibliothèque de cryptographie DOCA).
TASKS.md — workflows étape par étape pour les six verbes AES-GCM dans le champ d'application : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui oriente les questions hors du champ d'application vers la prochaine compétence appropriée.

La compétence suppose un hôte ou un BlueField où DOCA est déjà installé au lieu standard et l'utilisateur a les privilèges que son profil d'installation public attend. Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

Ce que cette compétence ne livre délibérément pas

Cette compétence est guidance pour l'agent, pas un bundle de samples ou templates. Pour garder la limite propre, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Code source d'application DOCA AES-GCM pré-écrit, dans n'importe quel langage. Le code source AES-GCM vérifié est les samples C livrés à /opt/mellanox/doca/samples/doca_aes_gcm/. Le job de l'agent est d'orienter l'utilisateur vers ces fichiers et de prescrire une modification minimum-diff sur eux via le workflow universel modifier-un-sample dans doca-programming-guide, stratifié avec les surcharges AES-GCM-spécifiques dans TASKS.md ## modify.
Vecteurs de test AES-GCM pré-calculés. La compétence dit à l'agent d'utiliser un vecteur de test publié (par exemple NIST GCMVS, exemples AES-GCM RFC 5288) comme la fumée de vecteur connu ; elle ne livre pas sa propre banque de vecteurs. L'agent doit citer la source du vecteur pour que l'utilisateur puisse l'auditer.
Clés AES-GCM pré-cuites, IVs, ou chaînes AAD. Une clé dans ce repo est une clé dans le repo de tous les clients — par construction, elle ne doit pas y être. La compétence enseigne la forme des entrées ; l'utilisateur fournit les vrais bytes de son propre système de gestion des clés.
Manifests de build autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) stationnés à l'intérieur de la compétence. L'agent construit le manifest de build dans le répertoire de projet de l'utilisateur par rapport au DOCA installé de l'utilisateur, où pkg-config --modversion doca-aes-gcm est la source de vérité.
Un subtree samples/, bindings/, ou reference/ d'aucune sorte. Un artifact mock ou incomplet dans l'arbre de cette compétence, même étiqueté « reference », est trompeur : les utilisateurs le liront comme buildable.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans le champ d'application.
Pour la matrice de capacité AES-GCM, les types de tâche, la surface de taille de clé, les règles de requête de capacité, la matrice de permission, la sémantique AEAD, la taxonomie d'erreurs, l'observabilité, et la politique de sécurité / sélection de chemin, voir CAPABILITIES.md.
Pour les workflows étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Les deux fichiers compagnons font des renvois croisés l'un vers l'autre, doca-version pour les règles canoniques de gestion des versions, et doca-public-knowledge-map chaque fois que la bonne réponse est « cherchez-le dans les docs publiques ou la disposition du paquet installé » plutôt que « guidance spécifique à AES-GCM ».

Compétences associées

doca-public-knowledge-map — la table de routage pour toutes les sources de documentation DOCA publiques et la disposition sur disque d'un paquet DOCA installé. La page DOCA AES-GCM vit à docs.nvidia.com/doca/sdk/DOCA-AES-GCM/ ; elle est un membre de la famille Accélération de Cryptographie DOCA aux côtés de doca-sha.
doca-setup — préparation d'env, vérification d'installation, et le chemin je n'ai pas d'installation encore avec le container DOCA NGC public. Cette compétence suppose que ses préconditions sont satisfaites.
doca-version — règles canoniques de gestion des versions DOCA. La ## Version compatibility de cette compétence fait des renvois croisés vers la règle de correspondance quatre voies et ajoute seulement le recouvrement AES-GCM-spécifique « découvrir les tailles de clé + la présence de tâche via requête cap ».
doca-structured-tools-contract — le contrat de règle de précédence des tools structurés du bundle (détecter / préférer / revenir à / rapporter). L'appendice Command dans TASKS.md honore ce contrat.
doca-programming-guide — modèles de programmation DOCA généraux partagés par chaque bibliothèque : le modèle de build pkg-config + meson canonique, le workflow de premier app modifier-un-sample-livré universel, le cycle de vie universel, la taxonomie cross-library DOCA_ERROR_*, et l'ordre de debug côté programme. Cette compétence stratifie les spécifiques AES-GCM au-dessus.
doca-sha — la bibliothèque sœur dans la famille Accélération de Cryptographie DOCA pour le hachage SHA accéléré matériellement. Chargez aux côtés de cette compétence quand le flow de l'utilisateur est chiffrement authentifié avec un hash keyed séparé (rare — AES-GCM fournit déjà l'authentification via son tag) ou quand l'utilisateur compare les chemins de déchargement entre les deux.
doca-debug — l'escalade de debug transversale (install / version / build / link / runtime / program / driver). Le debug spécifique à AES-GCM (taille-de-clé-non-supportée, entrée-surdimensionnée, échec-vérification-tag-au-déchiffrement) se stratifie au-dessus de cette escalade.