Moteur de déport SHA DOCA

Par où commencer : C'est une skill d'outil pour l'ENGINE OpenSSL livré dans l'arborescence des SOURCES DOCA sous doca/tools/sha_offload_engine/ et INSTALLÉ sur l'hôte sous ${DOCA_DIR}/tools/doca_sha_offload_engine/ en tant que libdoca_sha_offload_engine.so. Le changement de nom de répertoire (sha_offload_engine dans l'arborescence source vs doca_sha_offload_engine dans l'arborescence d'installation) est une convention d'empaquetage NVIDIA, pas une incohérence de bundle ; les deux formes apparaissent ci-dessous et sont le même artefact à différentes étapes du cycle de vie — citez celle qui correspond à votre question (build à partir des sources vs chargement à l'exécution). Ce n'est pas une CLI — c'est un objet partagé chargé par une application basée sur OpenSSL ou par openssl lui-même, qui redirige SHA-1 / SHA-256 / SHA-512 (une seule fois uniquement, via l'interface EVP_Digest) vers le chemin matériel DOCA SHA. Ouvrez TASKS.md et commencez par ## configure pour la configuration de l'adresse PCIe et les prérequis OpenSSL ; passez à ## run pour le flux « charger l'engine et prouver qu'il s'exécute réellement ». Ouvrez CAPABILITIES.md quand la question porte sur ce que l'engine déporte réellement vs sur quoi il revient en arrière, quand l'engine est un gain de perf vs non, ou comment vérifier que le déport s'est réellement engagé. Si DOCA n'est pas encore installé, consultez d'abord doca-setup. Si l'utilisateur construit un nouveau pipeline SHA à partir de zéro (plutôt que d'envelopper un pipeline basé sur OpenSSL existant), cette skill n'est pas la bonne surface — consultez plutôt ../../libs/doca-sha/SKILL.md.

Questions d'exemple que cette skill traite bien

Les CLASSES de questions doca-sha-offload-engine que cette skill est conçue pour traiter, chacune avec un exemple travaillé. La classe est l'élément porteur ; l'exemple travaillé est une instance.

« J'ai un pipeline basé sur OpenSSL existant qui effectue SHA ; puis-je déporter SHA sur DOCA sans réécrire l'app ? » — exemple travaillé : « l'app utilise EVP_DigestInit_ex / EVP_DigestUpdate / EVP_DigestFinal_ex sur EVP_sha256() ; puis-je déployer le déport DOCA-SHA via un chargement d'engine ? ». Répondu par la règle « quand cet engine est la bonne surface » dans CAPABILITIES.md ## Capabilities and modes + les mécaniques de chargement d'engine dans TASKS.md ## configure.
« L'engine s'est-il réellement chargé ? Ou OpenSSL est-il simplement revenu au SHA logiciel ? » — exemple travaillé : « mon invocation openssl dgst s'est terminée ; comment savoir que DOCA SHA a réellement effectué le travail et qu'OpenSSL n'a pas silencieusement utilisé le chemin logiciel ? ». Répondu par le motif « prouver que l'engine s'est réellement exécuté » dans CAPABILITIES.md ## Observability (le test négatif SHA-224 et le flag -engine_impl) + le flux de vérification dans TASKS.md ## test.
« Pour quelle plage de taille de message le déport d'engine est-il un gain vs SHA CPU ? » — exemple travaillé : « mon pipeline hash des blocs de 4 KB à la fois ; l'engine est-il un gain là, ou le aller-retour vers DOCA SHA coûte-t-il plus cher que le hash CPU lui-même ? ». Répondu par la règle de fenêtre de taille de message dans CAPABILITIES.md ## Capabilities and modes + le motif de comparaison de perf openssl speed dans TASKS.md ## test.
« Quels algorithmes SHA l'engine supporte-t-il réellement — et que se passe-t-il pour ceux qu'il ne supporte pas ? » — exemple travaillé : « mon pipeline mélange SHA-1, SHA-256, SHA-512 et SHA-224 — que fait l'engine pour chacun ? ». Répondu par la matrice de couverture d'algorithme dans CAPABILITIES.md ## Capabilities and modes.
« Dois-je utiliser cet engine ou appeler doca-sha directement ? » — exemple travaillé : « j'écris un nouveau service à partir de zéro ; l'engine m'économise-t-il du travail ou ajoute-t-il une complexité dont je n'ai pas besoin ? ». Répondu par le tableau de sélection « engine vs library » dans CAPABILITIES.md ## Capabilities and modes.
« Quelles versions d'OpenSSL l'engine nécessite-t-il, et qu'en est-il de la dépréciation de l'API ENGINE d'OpenSSL 3.x ? » — exemple travaillé : « mon hôte a OpenSSL 3.0 ; l'engine se chargera-t-il toujours ? ». Répondu par l'overlay de version dans CAPABILITIES.md ## Version compatibility (surface vérifiée : l'engine est documenté pour OpenSSL 1.1.1f sur Ubuntu 20.04 et OpenSSL 3.0.2 sur Ubuntu 22.04 selon le fichier readme.md livré).

Public

Cette skill sert les développeurs et opérateurs externes qui disposent d'un pipeline basé sur OpenSSL existant effectuant du hachage SHA et veulent déporter SHA sur DOCA SHA sans réécrire leur application par rapport à l'API C doca-sha. Concrètement :

Un développeur intégrant l'accélération DOCA SHA dans un service qui utilise déjà EVP_Digest pour SHA-1 / SHA-256 / SHA-512.
Un opérateur déployant un pipeline basé sur openssl dgst / openssl speed et voulant mesurer le gain du déport DOCA SHA sans modifier la surface d'invocation du pipeline.
Un SRE / ingénieur de performance produisant un artefact « voici le gain du déport d'engine vs SHA CPU sur ce mélange de tailles de message » pour informer une décision de changement de code (par exemple « devrions-nous adopter l'engine tel quel, ou réécrire pour doca-sha pour un contrôle plus fin ? »).
Un agent IA répondant « puis-je déployer DOCA SHA dans cette app basée sur OpenSSL sans changements de code » honnêtement — avec la matrice de couverture d'algorithme vérifiée, la fenêtre de taille de message, et le motif de vérification qui prouve que l'engine s'est réellement exécuté.

Ce n'est pas pour les utilisateurs construisant un nouveau pipeline SHA à partir de zéro (consultez ../../libs/doca-sha/SKILL.md), pas pour les utilisateurs voulant le déport MD5 / SHA-2-224 / SHA-3 / HMAC-SHA (l'engine n'implémente pas ceux-ci — la surface vérifiée selon la source de l'engine est SHA-1, SHA-256, SHA-512 une seule fois via EVP_Digest), et pas un substitut au guide de programmation public DOCA SHA.

Portée du langage

Le moteur de déport SHA DOCA est livré en tant qu'objet partagé dynamique C (libdoca_sha_offload_engine.so) construit à partir de doca/tools/sha_offload_engine/{engine/doca_sha_offload_engine.c, lib/doca_sha_offload_lib.{c,h}} via meson. Son interface de consommation est l'API ENGINE d'OpenSSL ; tout langage qui appelle OpenSSL (C, C++, Rust via le crate openssl, Python via cryptography et le backend pyca/cryptography, Node via node:crypto) peut donc utiliser l'engine, à condition que la liaison de langage appelle ENGINE_load_dynamic / ENGINE_by_id directement ou honore une config OpenSSL engines qui le charge. La contribution neutre au langage de la skill est les mécaniques de chargement d'engine et le motif de vérification ; l'API ENGINE d'OpenSSL est le contrat.

Quand charger cette skill

Chargez cette skill quand l'utilisateur est — ou l'agent doit — déployer le moteur de déport SHA DOCA dans un pipeline basé sur OpenSSL sur un hôte avec DOCA installé et un device capable de SHA. Concrètement :

Câbler l'engine dans une application basée sur OpenSSL existante ou une invocation CLI openssl, avec l'intention de ne pas faire de changements au niveau du code source (ou uniquement le bloc minimum ENGINE_load_dynamic / ENGINE_by_id montré dans le readme.md vérifié).
Vérifier que l'engine s'est réellement engagé pour les digests du chemin critique (la question « le déport est-il réel ou OpenSSL a-t-il basculé au logiciel »).
Caractériser la plage de taille de message sur laquelle l'engine est un gain de perf vs les chemins CPU sha1 / sha256 / sha512.
Décider entre « adopter l'engine » (pipeline existant, changement minimal) et « réécrire pour doca-sha » (nouveau pipeline, contrôle fin nécessaire).

Ne chargez pas cette skill pour les utilisateurs construisant un nouveau pipeline SHA à partir de zéro — consultez ../../libs/doca-sha/SKILL.md. Ne chargez pas cette skill pour les utilisateurs voulant des algorithmes que l'engine n'implémente pas (MD5, SHA-3, SHA-224, HMAC-SHA, SHA en streaming/incrémental via les chaînes EVP_DigestUpdate que l'engine traite comme une seule fois seulement).

Ce que cette skill fournit

C'est un chargeur fin. Le matériel substantif se trouve dans deux fichiers compagnons :

CAPABILITIES.md — ce que l'engine déporte (vérifié : SHA-1, SHA-256, SHA-512 une seule fois via l'interface haut niveau OpenSSL EVP_Digest), ce qu'il NE déporte PAS (tout le reste — y compris SHA-224, MD5, SHA-3, HMAC-SHA, et tout motif de chaîne EVP_DigestInit_ex / EVP_DigestUpdate / EVP_DigestFinal_ex que l'engine implémente en mettant en buffer puis en appelant DOCA SHA en une seule fois à Final), la règle de sélection engine-vs-library, la règle de fenêtre de taille de message pour quand le déport est un gain de perf, la surface ctrl-cmd vérifiée (set_pci_addr), l'overlay de version (OpenSSL ≥ 1.1.1 ; les tests livrés de l'engine couvrent OpenSSL 1.1.1f et OpenSSL 3.0.2 selon le readme.md ; OpenSSL 3.x déprécie l'API ENGINE mais la supporte toujours via le chemin de code legacy), la taxonomie d'erreur en couches, la surface d'observabilité (le motif « prouver que le déport s'est engagé » utilisant le test négatif SHA-224 et -engine_impl), et l'overlay de sécurité.
TASKS.md — workflows pas à pas pour les verbes de tâche dans le scope : install, configure (sélection d'adresse PCIe — l'engine utilise par défaut 03:00.0 et expose le ctrl-cmd set_pci_addr plus un override au moment du build selon le readme.md livré du test_cmdline_mode/), build (le flux meson), modify (refuse les patches de code source ; modifiez plutôt l'invocation au chargement et l'adresse PCIe), run (charger l'engine via openssl engine dynamic ; le motif de vérification ; le bloc ENGINE_load_dynamic programmatique OpenSSL), test (le test négatif SHA-224 « prouver que l'engine s'est exécuté » ; la comparaison de perf openssl speed ; la caractérisation de la fenêtre de taille de message), debug (parcourez la taxonomie d'erreur couche par couche), use (la décision engine-vs-library pour le pipeline spécifique de l'utilisateur), plus un bloc Deferred task verbs.

La skill suppose un hôte où DOCA est déjà installé, OpenSSL ≥ 1.1.1 est présent (libssl-dev ou équivalent), et l'opérateur dispose des privilèges que le profil d'installation public attend pour la liaison PCIe de l'engine.

Ce que cette skill ne livre délibérément pas

Cette skill est une guidance d'agent, pas un bundle d'exemples ou de scripts. Elle ne contient délibérément pas — et les pull requests ne devraient pas ajouter :

Code source d'application ENGINE OpenSSL pré-écrit au-delà du bloc vérifié verbatim dans le readme.md livré (la séquence ENGINE_load_dynamic / ENGINE_by_id / ENGINE_ctrl_cmd_string / ENGINE_init / ENGINE_set_default_digests, référencée croisée dans TASKS.md ## run). Le readme livré est l'exemple travaillé.
Un sous-arbre samples/, bindings/ ou reference/. C'est un chargeur fin pour un objet partagé livré ; le matériel substantif se trouve dans le readme.md livré et les docs de la bibliothèque doca-sha.
Numéros de performance à partir de la mémoire d'agent. La fenêtre de taille de message où l'engine gagne est spécifique au device, au firmware, à la version d'OpenSSL et à la charge de travail. Le motif de comparaison openssl speed dans TASKS.md ## test est le moyen de le capturer sur le matériel réel de l'utilisateur ; citer un numéro de mémoire est le mode de défaillance multiplateforme que cette skill existe pour prévenir.
Wrappers, parsers ou scripts dans n'importe quel langage qui consomment stdout de l'engine ou le format de sortie d'openssl speed.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans le scope (l'utilisateur dispose réellement d'un pipeline basé sur OpenSSL existant et veut déporter vers DOCA SHA sans changements de code ; si l'utilisateur construit à partir de zéro, consultez ../../libs/doca-sha/).
Pour ce que l'engine déporte vs sur quoi il revient en arrière, la règle de sélection engine-vs-library, la règle de fenêtre de taille de message, l'overlay de version, la taxonomie d'erreur, la surface d'observabilité (et le motif prouver-que-le-déport-s'est-réellement-engagé), et l'overlay de sécurité, voir CAPABILITIES.md.
Pour les workflows pas à pas — install, configure, build, modify, run, test, debug, use — voir TASKS.md.

Skills connexes

../../libs/doca-sha/SKILL.md — la bibliothèque DOCA SHA sous-jacente. L'engine est un wrapper OpenSSL-ENGINE fin autour de doca-sha ; quand l'utilisateur a besoin d'un contrôle fin sur la surface de tâche SHA (partial-hash, permissions de buffer personnalisées, cap-query pour des tailles de message inhabituelles), la bibliothèque est la bonne réponse. L'engine encapsule la tâche une-seule-fois ; la bibliothèque expose à la fois une-seule-fois et partial-hash selon ../../libs/doca-sha/CAPABILITIES.md#capabilities-and-modes.
doca-version — la chaîne canonique de détection de version. L'engine a un overlay de version DEUX-AXES (côté DOCA et côté OpenSSL) ; la skill de version porte la règle d'appairage quatre-voies que cette skill en couche au-dessus.
doca-debug — l'échelle de debug transversale. L'engine surfaces sa propre taxonomie d'erreur ; quand la cause est en dessous de DOCA (driver, firmware), la taxonomie remet les mains ici.
doca-setup — préparation d'env, vérification d'installation, le chemin d'installation de libssl-dev, et le chemin de conteneur NGC DOCA.
doca-public-knowledge-map — routage vers l'ensemble de documentation publique DOCA SHA sur docs.nvidia.com/doca/sdk/ et vers la documentation upstream ENGINE OpenSSL / openssl-engine sur openssl.org.
doca-hardware-safety — la méta-politique de sécurité matérielle au niveau du bundle. L'engine se lie à un device PCIe spécifique ; le ctrl set_pci_addr est l'overlay spécifique à l'artefact, mais tout changement côté hôte en dessous (burn de firmware, reflash BFB) passe par la méta-politique.