Provided by: manpages-fr-extra_20151231_all 
NOM
moteur - ENGINE module de support cryptographique
SYNOPSIS
#include <openssl/engine.h>
ENGINE *ENGINE_get_first(void);
ENGINE *ENGINE_get_last(void);
ENGINE *ENGINE_get_next(ENGINE *e);
ENGINE *ENGINE_get_prev(ENGINE *e);
int ENGINE_add(ENGINE *e);
int ENGINE_remove(ENGINE *e);
ENGINE *ENGINE_by_id(const char *id);
int ENGINE_init(ENGINE *e);
int ENGINE_finish(ENGINE *e);
void ENGINE_load_openssl(void);
void ENGINE_load_dynamic(void);
#ifndef OPENSSL_NO_STATIC_ENGINE
void ENGINE_load_4758cca(void);
void ENGINE_load_aep(void);
void ENGINE_load_atalla(void);
void ENGINE_load_chil(void);
void ENGINE_load_cswift(void);
void ENGINE_load_gmp(void);
void ENGINE_load_nuron(void);
void ENGINE_load_sureware(void);
void ENGINE_load_ubsec(void);
#endif
void ENGINE_load_cryptodev(void);
void ENGINE_load_builtin_engines(void);
void ENGINE_cleanup(void);
ENGINE *ENGINE_get_default_RSA(void);
ENGINE *ENGINE_get_default_DSA(void);
ENGINE *ENGINE_get_default_ECDH(void);
ENGINE *ENGINE_get_default_ECDSA(void);
ENGINE *ENGINE_get_default_DH(void);
ENGINE *ENGINE_get_default_RAND(void);
ENGINE *ENGINE_get_cipher_engine(int nid);
ENGINE *ENGINE_get_digest_engine(int nid);
int ENGINE_set_default_RSA(ENGINE *e);
int ENGINE_set_default_DSA(ENGINE *e);
int ENGINE_set_default_ECDH(ENGINE *e);
int ENGINE_set_default_ECDSA(ENGINE *e);
int ENGINE_set_default_DH(ENGINE *e);
int ENGINE_set_default_RAND(ENGINE *e);
int ENGINE_set_default_ciphers(ENGINE *e);
int ENGINE_set_default_digests(ENGINE *e);
int ENGINE_set_default_string(ENGINE *e, const char *list);
int ENGINE_set_default(ENGINE *e, unsigned int flags);
unsigned int ENGINE_get_table_flags(void);
void ENGINE_set_table_flags(unsigned int flags);
int ENGINE_register_RSA(ENGINE *e);
void ENGINE_unregister_RSA(ENGINE *e);
void ENGINE_register_all_RSA(void);
int ENGINE_register_DSA(ENGINE *e);
void ENGINE_unregister_DSA(ENGINE *e);
void ENGINE_register_all_DSA(void);
int ENGINE_register_ECDH(ENGINE *e);
void ENGINE_unregister_ECDH(ENGINE *e);
void ENGINE_register_all_ECDH(void);
int ENGINE_register_ECDSA(ENGINE *e);
void ENGINE_unregister_ECDSA(ENGINE *e);
void ENGINE_register_all_ECDSA(void);
int ENGINE_register_DH(ENGINE *e);
void ENGINE_unregister_DH(ENGINE *e);
void ENGINE_register_all_DH(void);
int ENGINE_register_RAND(ENGINE *e);
void ENGINE_unregister_RAND(ENGINE *e);
void ENGINE_register_all_RAND(void);
int ENGINE_register_STORE(ENGINE *e);
void ENGINE_unregister_STORE(ENGINE *e);
void ENGINE_register_all_STORE(void);
int ENGINE_register_ciphers(ENGINE *e);
void ENGINE_unregister_ciphers(ENGINE *e);
void ENGINE_register_all_ciphers(void);
int ENGINE_register_digests(ENGINE *e);
void ENGINE_unregister_digests(ENGINE *e);
void ENGINE_register_all_digests(void);
int ENGINE_register_complete(ENGINE *e);
int ENGINE_register_all_complete(void);
int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
long i, void *p, void (*f)(void), int cmd_optional);
int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
int cmd_optional);
int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
void *ENGINE_get_ex_data(const ENGINE *e, int idx);
int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
ENGINE *ENGINE_new(void);
int ENGINE_free(ENGINE *e);
int ENGINE_up_ref(ENGINE *e);
int ENGINE_set_id(ENGINE *e, const char *id);
int ENGINE_set_name(ENGINE *e, const char *name);
int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth);
int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth);
int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth);
int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
int ENGINE_set_flags(ENGINE *e, int flags);
int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
const char *ENGINE_get_id(const ENGINE *e);
const char *ENGINE_get_name(const ENGINE *e);
const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e);
const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e);
const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e);
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
int ENGINE_get_flags(const ENGINE *e);
const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
UI_METHOD *ui_method, void *callback_data);
EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
UI_METHOD *ui_method, void *callback_data);
void ENGINE_add_conf_module(void);
DESCRIPTION
Ces fonctions créent, manipulent et utilisent des modules cryptographiques sous la forme
d'objets ENGINE. Ces objets servent de conteneurs pour les implémentations d'algorithmes
cryptographiques, et ils gèrent un mécanisme de comptage de référence qui les autorisent à
être chargés de façon dynamique dans l'application exécutée et en dehors.
La fonctionnalité cryptographique qui peut être fournie par l'implémentation d'un ENGINE
inclut les abstractions suivantes :
RSA_METHOD - pour fournir une implémentation RSA alternative
DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD,
STORE_METHOD - identique pour d'autres API d'OpenSSL
EVP_CIPHER - potentiellement plusieurs algorithmes de chiffrement (indexé par 'nid')
EVP_DIGEST - potentiellement plusieurs algorithmes de hachage (indexé par 'nid')
key-loading - chargement des clés EVP_PKEY publiques/privées
Référence de calculs et traitements
À cause de la nature modulaire de l'API ENGINE, les pointeurs vers les ENGINE doivent être
traités comme des références abstraites vers des ressources — c'est-à-dire pas seulement
comme des pointeurs, mais aussi comme des références vers l'objet ENGINE sous-jacent.
C'est-à-dire que l'on doit obtenir une nouvelle référence lors de la copie d'un pointeur
vers un ENGINE si la copie doit être utilisée (et libérée) de façon indépendante.
Les objets ENGINE ont deux niveaux de comptage de références pour correspondre à la façon
dont les objets sont utilisés. À plus bas niveau, chaque pointeur ENGINE est
intrinsèquement une référence structurelle - une référence structurelle est nécessaire
pour utiliser toute valeur de pointeur, car ce type de référence garantit que la structure
ne peut pas être désallouée avant que sa référence ne soit libérée.
Mais, une référence structurelle n'offre aucune garantie que l'ENGINE soit initialisé et
capable d'utiliser n'importe laquelle de ses implémentations cryptographiques. En effet,
il est fort probable que la plupart des ENGINE ne puissent pas s'initialiser dans des
environnements typiques, car les ENGINES sont généralement utilisés pour gérer du matériel
spécialisé. Pour utiliser une fonctionnalité d'ENGINE, il est nécessaire d'avoir une
référence fonctionnelle. Cette référence peut être considérée comme une forme spécialisée
de référence structurelle, car chaque référence fonctionnelle contient de façon implicite
une référence structurelle. Par contre, pour éviter d'avoir des programmes durs à
déboguer, il est recommandé de traiter ces deux types de référence indépendamment l'une de
l'autre. Si une référence fonctionnelle est disponible pour un ENGINE, il est garanti que
cet ENGINE a été initialisé et est prêt à faire des opérations cryptographiques et restera
non-initialisable jusqu’à la libération de la référence.
Structural references
Ce type de référence de base est utilisé pour instancier de nouveaux ENGINE, itérer sur
les listes liées d'ENGINE chargés d'OpenSSL, lire les informations d'un ENGINE, etc. Une
référence structurelle est essentiellement suffisante pour des requêtes ou pour manipuler
les données d'implémentation d'un ENGINE au lieu d'utiliser ses fonctionnalités.
La fonction ENGINE_new() renvoie une référence structurelle vers un objet ENGINE vide. Il
y a d'autres fonctions d'API dans ENGINE qui renvoient une référence structurelle comme :
ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next(),
ENGINE_get_prev(). Toute référence structurelle devrait être libérée par un appel
correspondant à la fonction ENGINE_free() — l'objet ENGINE lui-même ne sera nettoyé et
désalloué que lorsque la dernière référence structurelle sera libérée.
On doit aussi remarquer que beaucoup d'appels de fonctions d'API d'ENGINE qui acceptent
une référence structurelle obtiendront de façon interne une autre référence — en général
cela ce produira lorsque l'ENGINE sera nécessaire à OpenSSL après le retour de la
fonction. Exemple : la fonction d'ajout d'un nouvel ENGINE à la liste interne d'OpenSSL
est ENGINE_add() — si cette actionse termine avec succès, alors OpenSSL aura stocké une
nouvelle référence structurelle en interne, aussi l'appelant est toujours responsable de
la libération de ses propres références avec ENGINE_free() quand les fonctions n'en ont
plus besoin. D'une façon similaire, certaines fonctions libéreront automatiquement la
référence structurelle qui leur est donnée si une partie du travail de la fonction est de
faire cela. Exemple : les fonctions ENGINE_get_next() et ENGINE_get_prev() sont utilisées
pour itérer à travers la liste interne d'ENGINE — elles renverront une nouvelle référence
structurelle au prochain (ou précédent) ENGINE dans la liste ou NULL si elles sont à la
fin (ou au début) de la liste, mais, dans tous les cas, la référence structurelle passée à
la fonction est libérée au nom de l'appelant.
Pour éclaircir la façon dont une fonction traite les références, on doit toujours
consulter la documentation en utilisant la page man de cette fonction, ou à défaut
l’en-tête openssl/engine.h qui contient des indices.
Références fonctionnelles
Comme mentionné, les références fonctionnelles existent lorsque la fonctionnalité
cryptographique d'un ENGINE doit être disponible. Une référence fonctionnelle peut être
obtenue de plusieurs façons : d'une référence structurelle pré-existante demandée par
l'ENGINE, ou en demandant à l'ENGINE par défaut d'OpenSSL pour une tâche cryptographique
donnée.
Pour obtenir une référence fonctionnelle à partir d'une référence structurelle, appelez la
fonction ENGINE_init(). Cela renvoie 0 si l'ENGINE n'était pas déjà opérationnel et ne
pouvait donc pas être initialisé (ex : le manque de pilotes dans le système, pas de
matériel spécifique attaché, etc), sinon elle renverra autre chose que 0 pour indiquer que
l'ENGINE est maintenant opérationnel et a alloué une référence fonctionnelle à l'ENGINE.
Toutes les références fonctionnelles sont libérées en appelant ENGINE_finish() (ce qui
supprime les références structurelles implicites aussi).
La deuxième façon de récupérer des références fonctionnelles est de demander à OpenSSL une
implémentation par défaut pour la tâche voulue, ex : avec ENGINE_get_default_RSA(),
ENGINE_get_default_cipher_engine(), etc. Celles-ci sont expliquées dans la prochaine
partie, mais elles ne sont d'habitude pas requises par les programmeurs d'application car
elles sont utilisées automatiquement quand les spécificités de types de l'algorithme dans
OpenSSL sont créées et utilisées, comme RSA, DSA, EVP_CIPHER_CTX, etc.
Implémentations par défaut
Pour chaque abstraction gérée, le code d'ENGINE maintient une table d'état de contrôle
interne dans laquelle les implémentations sont disponibles pour une abstraction donnée et
qui devrait être utilisée par défaut. Ces implémentations sont enregistrées dans les
tables et indexées par une valeur « nid », parce que les abstractions comme EVP_CIPHER et
EVP_DIGEST gèrent énormément d'algorithmes et de modes distincts, et les ENGINE peuvent
arbitrairement tous les prendre en charge. Dans le cas d'autres abstractions comme RSA,
DSA, etc, il n'y a qu'un seul « algorithme » donc toutes les implémentations sont
enregistrées de façon implicite en utilisant le même index « nid ».
Quand une requête d'un ENGINE par défaut pour une abstraction/algorithme/mode est faite
(par ex. en appelant RSA_new_method(NULL)), un appel « get_default » peut être fait au
sous-système de l'ENGINE pour traiter l'état de la table correspondante et renvoyer une
référence fonctionnelle vers un ENGINE initialisé dont l'implémentation devrait être
utilisée. Si aucun ENGINE ne doit (ou ne peut) être utilisé, elle renverra NULL et
l'appelant opérera avec un identificateur d'ENGINE NULL — cela correspond à utiliser
l'implémentation conventionnelle d'un programme. Dans ce cas, OpenSSL fonctionnera de la
même façon qu'avant que l'API ENGINE n'existe.
Chaque table d'état a un drapeau pour indiquer si elle a traité cette requête
« get_default » depuis que la table a été modifiée, car pour traiter cette question elle
doit itérer à travers tous les ENGINE enregistrés dans la table en essayant de les
initialiser les uns après les autres, au cas où l'un d'entre eux soit opérationnel. Si
elle renvoie une référence fonctionnelle vers un ENGINE, elle mettra en cache une autre
référence pour accélérer le processus en cas de futures requêtes (plus besoin d'avoir à
itérer sur toute la table). De même, elle mettra en cache une réponse NULL si aucun ENGINE
n'est disponible pour que les futures requêtes ne fassent pas la même itération, sauf si
l'état de la table change. Ce comportement peut aussi être changé ; si le drapeau
ENGINE_TABLE_FLAG_NOINIT est défini (en utilisant ENGINE_set_table_flags()), il n'y aura
pas de tentatives d'initialisation, et la seule façon pour une table d'état de renvoyer à
un ENGINE non NULL pour la requête « get_default » sera celle qui sera indiquée de façon
explicite dans la table. Exemple : ENGINE_set_default_RSA() fait la même chose
qu'ENGINE_register_RSA() sauf qu'elle définit aussi le cache de réponses de la table pour
la requête « get_default ». Dans ce cas, les abstractions comme EVP_CIPHER, où les
implémentations sont indexées par un « nid », ces drapeaux et réponses cachés sont
différents des valeurs « nid ».
Exigences de l'application
Cette partie expliquera les choses de base qu'un programmeur d'applications doit connaître
pour rendre disponibles les éléments les plus utiles de la fonctionnalité d'ENGINE à
l'utilisateur. La première chose à considérer est si le programmeur veut fournir un module
alternatif d'ENGINE disponible à l'application et à l'utilisateur. OpenSSL maintient une
liste liée interne d'ENGINE « visibles » qu'il a besoin d'opérer — au démarrage, cette
liste est vide et d'ailleurs si une application n'utilise pas d'appel de l'API d'ENGINE et
qu'elle utilise un lien statique envers openssl, alors le binaire de l'application
résultante ne contiendra aucun code d'ENGINE alternatif. La première considération est
donc de savoir si toute implémentation d'ENGINE doit être rendue visible à OpenSSL — cela
est contrôlé en appelant les différentes fonctions de « chargement », exemple :
/* Rendre l'ENGINE S<« dynamique »> disponible */
void ENGINE_load_dynamic(void);
/* Rendre le support d'accélération matériel CryptoSwift disponible */
void ENGINE_load_cswift(void);
/* Rendre le support de matériel S<« CHIL »> de nCipher disponible */
void ENGINE_load_chil(void);
...
/* Rendre toutes les implémentations du paquet OpenSSL disponibles. */
void ENGINE_load_builtin_engines(void);
Après avoir appelé n'importe laquelle de ces fonctions, les objets ENGINE ont été alloués
de façon dynamique, peuplés avec ces implémentations et liés à la liste chaînée interne
d'OpenSSL. À partir de ce moment il est nécessaire de mentionner une fonction de l'API
importante ;
void ENGINE_cleanup(void);
Si aucune fonction d'API ENGINE n'est appelée dans une application, alors il n'y a pas de
fuite mémoire dont il faut s'inquiéter dans les fonctionnalités d'ENGINE ; néanmoins, si
n'importe quel ENGINE est chargé, même s'il n'est jamais enregistré ou utilisé, il est
nécessaire d'utiliser la fonction ENGINE_cleanup() pour le nettoyer de façon correcte
avant la fermeture du programme, si l'utilisateur veut éviter les fuites mémoires. Ce
mécanisme utilise une table enregistrant les rétroactions internes pour qu'une
fonctionnalité d'API ENGINE, qui sait qu'elle a besoin d'être nettoyée, puisse enregistrer
les détails du nettoyage à appeler pendant l'appel deENGINE_cleanup(). Cette approche
permet à ENGINE_cleanup() de nettoyer après n'importe quelle utilisation par un programme
d'une fonctionnalité d'ENGINE, mais cela ne crée pas de lien de dépendance à toutes les
fonctionnalités possibles d'ENGINE — seules les rétroactions de nettoyage nécessaires aux
fonctionnalités utilisées, seront requises par le lieur.
Le fait que les ENGINES sont rendus visibles à OpenSSL (et de ce fait sont liés au
programme et chargés en mémoire lors de l'exécution) ne veut pas dire qu'ils sont
« enregistrés » ou appelés et utilisés par OpenSSL automatiquement — ce comportement est
quelque chose qui doit être contrôlé par l'application. Certaines applications auront
besoin d'autoriser l'utilisateur à spécifier exactement quel ENGINE il voudra utiliser si
il y en a un qui doit être utilisé. D'autres préféreront tout charger pour que OpenSSL
utilise automatiquement le premier ENGINE qui peut s'initialiser correctement
— c'est-à-dire, qui puisse correspondre à une accélération matérielle attachée à la
machine, ou quelque chose comme cela. Il y a probablement énormément d'autres façons par
lesquelles l'application peut préférer gérer les choses, nous illustrerons donc simplement
les conséquences telles qu'elles s'appliquent à des cas simples et laisserons les
développeurs considérer ces cas et le code source de fonctions utilitaires d'OpenSSL comme
guide.
Utiliser une implémentation spécifique d'ENGINE
Ici, nous allons supposer qu'une application a été configurée par son utilisateur ou
administrateur pour utiliser l'ENGINE « ACME » s'il est disponible dans la version
d'OpenSSL avec laquelle l'application a été compilée. S'il est disponible, il devra être
utilisé par défaut pour tous les chiffrements RSA, DSA et les opérations par chiffrement
symétrique, sinon OpenSSL devrait utiliser ses fonctionnalités internes comme d'habitude.
Le code suivant illustre comment faire cela :
ENGINE *e;
const char *engine_id = "ACME";
ENGINE_load_builtin_engines();
e = ENGINE_by_id(engine_id);
if(!e)
/* le moteur n'est pas disponible */
return;
if(!ENGINE_init(e)) {
/* le moteur n'a pas pu être initialisé, libérer « e » */
ENGINE_free(e);
return;
}
if(!ENGINE_set_default_RSA(e))
/* Ceci devrait uniquement se produire quand S<« e »> ne peut être
* initialisé, mais la déclaration précédente suggère qu'il l'a été. */
abort();
ENGINE_set_default_DSA(e);
ENGINE_set_default_ciphers(e);
/* Libère la référence fonctionnelle d'ENGINE_init() */
ENGINE_finish(e);
/* Libère la référence structurelle d'ENGINE_by_id() */
ENGINE_free(e);
Utiliser automatiquement les implémentations intégrées d'ENGINE
Ici, nous allons supposer que l'on veut charger et enregistrer toutes les implémentations
d'ENGINE fournies avec OpenSSL, de façon à ce que n'importe quel algorithme de
cryptographie qui est utilisé par OpenSSL — s'il y a un ENGINE qui l'implémente et peut
être initialisé — alors il sera utilisé. Le code suivant montre un exemple d'utilisation :
/* Charger et rendre visible tous les paquets ENGINE dans la mémoire. */
ENGINE_load_builtin_engines();
/* Enregistrer tous les paquets pour tous les algorithmes qu'ils implémentent collectivement */
ENGINE_register_all_complete();
Cela est tout ce qui est requis. Par exemple, la prochaine fois qu'OpenSSL essaye de
mettre en place une clé RSA, n'importe quel ENGINE fourni qui implémente RSA_METHOD sera
passé à ENGINE_init() et si l'un d'entre eux réussit, cet ENGINE sera choisi par défaut
pour l'utilisation de RSA.
Support de configuration avancé
Il y a un mécanisme géré par le framework de l'ENGINE qui autorise chaque implémentation
d'ENGINE de définir un nombre arbitraire d'ensembles de « commandes » de configuration, de
les révéler à OpenSSL et toute application basée sur OpenSSL. Ce mécanisme est entièrement
basé sur l'utilisation de couple noms-valeurs et suppose que l'entrée est au format ASCII
(pas d'unicode ou d'UTF pour l'instant !), c'est donc idéal si l'application veut fournir
une possibilité de fournir, d'une façon transparente aux utilisateurs, des « directives »
de configuration arbitraires directement à ces ENGINE. Il permet aussi à l'application de
demander de façon dynamique à l'implémentation de l'ENGINE des noms, descriptions et
drapeaux d'entrée des « commandes de contrôle » disponibles, ce qui fournit un programme
plus flexible. Or, si l'utilisateur s'attend à connaitre quel ENGINE il utilise (dans le
cas de matériel spécialisé, cela va sans dire) alors l'application peut ne pas
s'intéresser à la découverte des commandes de contrôle gérées et plus simplement préférer
passer des réglages directement à l'ENGINE tels qu'ils sont fournis par l'utilisateur.
Avant d'illustrer les commandes de contrôle, il est raisonnable de mentionner ce pour quoi
elles sont utilisées. De façon générale, il y a deux utilisations de commandes de
contrôle ; la première consiste à fournir les détails nécessaires à l'implémentation (qui
peut ne rien connaître du système hôte) pour que l'initialisation se fasse. Cela peut
inclure n'importe quel chemin de pilote ou de fichier config qui doit être chargé, des
adresses réseau requises, des identifiants de cartes à puce, des mots de passe pour
initialiser des dispositifs sécurisés, des informations de connexion, etc. Cette classe de
commandes a généralement besoin d'être passée à un ENGINE avant d'essayer de
l'initialiser, c'est-à-dire avant d'appeler ENGINE_init(). L'autre classe de commande
consiste en des réglages ou des opérations qui modifient certains comportements ou
déclenchent la réalisation de certaines opérations, et ces commandes peuvent fonctionner
avant ou après ENGINE_init(), ou dans certains cas avant et après. L'implémentation
d'ENGINE doit fournir des indications de cela dans la description des commandes de
contrôle intégrées et/ou dans la documentation externe finale.
Envoyer des commandes de contrôle à un ENGINE
Illustrons cela grâce à un exemple : une fonction pour laquelle l'appelant fournit le nom
de l'ENGINE qu'il veut utiliser, une table de paires de chaînes de caractères à utiliser
avant l'initialisation, et d'autres tables après l'initialisation. Notez que les paires de
chaînes de caractères utilisées pour les commandes de contrôles consistent en un « nom »
de commande suivit du « paramètre » de la commande — le paramètre pourrait être NULL dans
certains cas mais le nom ne peut pas l'être. Cette fonction devrait initialiser l'ENGINE
(en envoyant les « pré » commandes avant et les « post » commandes après) et le régler
comme défaut pour tout sauf RAND, puis renvoyer un booléen pour un succès ou un échec.
int generic_load_engine_fn(const char *engine_id,
const char **pre_cmds, int pre_num,
const char **post_cmds, int post_num)
{
ENGINE *e = ENGINE_by_id(engine_id);
if(!e) return 0;
while(pre_num--) {
if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
pre_cmds[0], pre_cmds[1] ? S<pre_cmds[1] :> "(NULL)");
ENGINE_free(e);
return 0;
}
pre_cmds += 2;
}
if(!ENGINE_init(e)) {
fprintf(stderr, "Failed initialisation\n");
ENGINE_free(e);
return 0;
}
/* ENGINE_init() a renvoyé une référence fonctionnelle, il faut donc libérer la référence structurelle d'ENGINE_by_id(). */
ENGINE_free(e);
while(post_num--) {
if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
post_cmds[0], post_cmds[1] ? S<post_cmds[1] :> "(NULL)");
ENGINE_finish(e);
return 0;
}
post_cmds += 2;
}
ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
/* Succès */
return 1;
}
Notez qu'ENGINE_ctrl_cmd_string() accepte un argument booléen qui peut assouplir les
sémantiques de la fonction — s'il est différent de 0, elle ne renverra un échec que si
l'ENGINE prend en charge le nom de la commande mais a échoué lors de son exécution ; si
l'ENGINE ne prend pas en charge le nom de la commande, elle renverra simplement succès
sans rien faire. Dans ce cas, on suppose que l'utilisateur apporte des commandes
spécifiques à l'ENGINE donné, on règle donc cela à FALSE.
Découverte de commandes de contrôle gérées
Il est possible de découvrir les noms, id numériques, descriptions et paramètres d'entrée
des commandes de contrôle prises en charge par un ENGINE au moment de l'exécution en
utilisant une référence structurelle. Notez que certaines commandes de contrôle définies
dans OpenSSL intercepteront et géreront ces appels au nom d'ENGINE, c'est-à-dire le
gestionnaire ctrl() d'ENGINE n'est pas utilisé pour les commandes de contrôle.
openssl/engine.h définit un index, ENGINE_CMD_BASE, à partir duquel toutes les commandes
de contrôle implémentées par ENGINE doivent être numérotées. Toute valeur de commande plus
basse que ce symbole est considérée comme « générique » et est gérée directement par les
routines noyau d'OpenSSL.
C'est en utilisant ces contrôles « essentiels » que l'on peut découvrir les commandes de
contrôle implémentées par un ENGINE donné, plus spécifiquement ces commandes :
#define ENGINE_HAS_CTRL_FUNCTION 10
#define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11
#define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12
#define ENGINE_CTRL_GET_CMD_FROM_NAME 13
#define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14
#define ENGINE_CTRL_GET_NAME_FROM_CMD 15
#define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16
#define ENGINE_CTRL_GET_DESC_FROM_CMD 17
#define ENGINE_CTRL_GET_CMD_FLAGS 18
Alors que ces commandes sont traitées de façon automatique par le code du framework
d'OpenSSL, elles utilisent diverses propriétés exposées par chaque ENGINE pour traiter ces
requêtes. Un ENGINE a 3 propriétés qu'il expose qui peuvent affecter comment celles-ci se
comportent ; il peut fournir un contrôleur ctrl(), il peut spécifier
ENGINE_FLAGS_MANUAL_CMD_CTRL dans les drapeaux de l'ENGINE, et il peut exposer un tableau
de descriptions de commandes de contrôle. Si un ENGINE spécifie le drapeau
ENGINE_FLAGS_MANUAL_CMD_CTRL, alors les commandes essentielles de contrôle seront
simplement passées directement au gestionnaire ctrl() de l'ENGINE (et de ce fait, il doit
y en avoir un de fourni), c'est donc le rôle de l'ENGINE de répondre à ces commandes
« découvertes ». Si un drapeau n'est pas déterminé, alors le code du framework d'OpenSSL
fonctionnera avec les règles suivantes :
si aucun gestionnaire ctrl() n'est S<fourni ;>
ENGINE_HAS_CTRL_FUNCTION renvoie FALSE (zero),
toutes les autres commandes échouent.
si un gestionnaire ctrl() a été fourni mais aucun tableau de commandes de contrôle n'a été S<fourni ;>
ENGINE_HAS_CTRL_FUNCTION renvoie TRUE,
toutes les autres commandes échouent.
si un gestionnaire ctrl() et un tableau de commandes ont été S<fournis ;>
ENGINE_HAS_CTRL_FUNCTION renvoie TRUE,
toutes les autres commandes continuent leurs traitements ...
Si le tableau de commandes de contrôle d'ENGINE est vide alors toutes les autres commandes
échoueront, sinon ENGINE_CTRL_GET_FIRST_CMD_TYPE renvoie l'identifiant de la première
commande prise en charge par l'ENGINE, ENGINE_GET_NEXT_CMD_TYPE prend l'identifiant d'une
commande prise en charge par l'ENGINE et renvoie le prochain identifiant de commande, ou
échoue s'il n'y en a plus, ENGINE_CMD_FROM_NAME prend un nom sous forme de chaîne de
caractères pour une commande et renvoie l'identifiant correspondant ou échoue si la
commande correspondante n'existe pas. Les commandes restantes prennent un identifiant de
commande et renvoient les propriétés de la commande correspondante. Toutes, sauf
ENGINE_CTRL_GET_FLAGS, renvoient la longueur de la chaîne de caractères du nom de la
commande ou de la description, ou remplissent un tampon de caractères fourni avec la copie
du nom ou de la description de la commande. ENGINE_CTRL_GET_FLAGS renvoie un masque OR bit
à bit ayant les valeurs possibles suivantes :
#define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001
#define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002
#define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004
#define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008
Si le drapeau ENGINE_CMD_FLAG_INTERNAL est défini, alors n'importe quels autres drapeaux
sont purement informationnels pour l'appelant — ce drapeau empêchera la commande d'être
exécutée par les fonctions haut niveau d'un ENGINE comme ENGINE_ctrl_cmd_string(). Les
commandes « INTERNES » ne sont pas supposées être exposées à des configurations basées sur
du texte par les applications, administrations, utilisateurs, etc. Celles-ci peuvent gérer
des opérations arbitraires à l’aide d'ENGINE_ctrl(), y compris le passage de ou vers les
données des commandes de contrôle de n'importe quel type arbitraire. Ces commandes sont
gérées dans le mécanisme de découverte pour simplement autoriser les applications à
déterminer si un ENGINE gère certaines commandes spécifiques qu'il veut utiliser (par
exemple : l'application « foo » veut faire une requête à différents ENGINE pour voir s'ils
implémentent « FOO_GET_VENDOR_LOGO_GIF », et ENGINE peut de ce fait décider s'il prend en
charge ou non cette extension spécifique à « foo »).
Développements futurs
L'API d'ENGINE et sa structure architecturale interne sont en cours de révision. Il est
prévu d'avoir de nouvelles modifications dans la version 0.9.8 pour une prise en charge du
chargement transparent d'ENGINE « dynamiques » (implémentés comme bibliothèques partagées
autonomes). Cela devrait autoriser de fournir des implémentations ENGINE indépendamment
des bibliothèques d'OpenSSL ou des applications basées sur OpenSSL, et supprimera aussi
toute obligation pour les applications d'utiliser explicitement l'ENGINE « dynamique »
pour se lier à des implémentations de bibliothèques partagées.
VOIR AUSSI
rsa(3), dsa(3), dh(3), rand(3)
TRADUCTION
La traduction de cette page de manuel est maintenue par les membres de la liste
<debian-l10n-french AT lists DOT debian DOT org>. Veuillez signaler toute erreur de
traduction par un rapport de bogue sur le paquet manpages-fr-extra.