CONFIG(5ssl) OpenSSL CONFIG(5ssl) NOM config -- Fichiers de configuration de la bibliotheque OpenSSL CONF DESCRIPTION Cette page documente la syntaxe des fichiers de configuration d'OpenSSL tels qu'ils sont analyses par NCONF_load(3) et les fonctions liees. Ce format est utilise par de nombreuses commandes d'OpenSSL, ainsi que pour initialiser les bibliotheques lors de leur utilisation par une application. La premiere partie decrit la syntaxe generale des fichiers de configuration et les sections suivantes decrivent les semantiques des modules individuels. D'autres modules sont decrits dans fips_config(5) et x509v3_config(5). La syntaxe de la definition des valeurs d'ASN.1 est decrite dans ASN1_generate_nconf(3). SYNTAXE Un fichier de configuration est une serie de lignes. Les lignes blanches et les espaces entre les elements d'une ligne n'ont pas de signification. Un commentaire debute par le caractere # ; le reste de la ligne est ignore. Si le # est le premier caractere (qui n'est pas un espace) dans une ligne, la ligne entiere est ignoree. Directives Deux directives, .include et .pragma peuvent etre utilisees pour controler l'analyse des fichiers de configuration. Pour assurer une compatibilite avec les versions plus anciennes d'OpenSSL, un signe egal apres la directive est ignore. Les versions plus anciennes le traitent comme une affectation, aussi il faut prendre des precautions si la difference dans les semantiques est importante. Un fichier peut en inclure d'autres avec la syntaxe include : .include [=] chemin Si chemin est un fichier simple, ce fichier est inclus directement a cet emplacement. Les fichiers inclus peuvent avoir des affectations .include qui specifient d'autres fichiers. Si chemin est un repertoire, tous les fichiers dans ce repertoire qui possedent l'extension ".cnf" ou ".conf" seront inclus, (disponible seulement dans les systemes qui gerent les entrees-sorties POSIX). Les sous-directoires trouves dans le chemin sont ignores. De la meme facon, si un fichier est ouvert pendant le balayage d'un repertoire et si ce fichier contient une directive .include qui specifie un repertoire, elle est aussi ignoree. Comme regle generale, le chemin devrait etre un chemin absolu ; cela peut etre impose avec les directives abspath et includedir decrites plus loin. La variable d'environnement OPENSSL_CONF_INCLUDE, si elle existe, est ajoutee au debut de tous les chemins relatifs. Si le chemin est encore relatif, il est interprete par rapport au repertoire de travail en cours. Pour obliger toutes les inclusions de fichier a nommer des chemins absolus, utilisez la directive suivante : .pragma [=] abspath:valeur Le comportement par defaut, ou la valeur est false ou off, est de permettre des chemins relatifs. Pour exiger que tous les chemins .include soient des chemins absolus, utilisez une valeur de true ou on. Dans ces fichiers, le signe dollar, $, est utilise pour referencer une variable, comme decrit ci-dessous. Sur certaines plateformes, neanmoins, il est courant de traiter $ comme un caractere normal dans les noms de symbole. La prise en charge de ce comportement peut etre obtenu avec la directive suivante : .pragma [=] dollarid:valeur Le comportement par defaut, ou la valeur est false ou off, est de traiter le signe dollar comme l'indication d'un nom de variable ; "toto$truc"' est interprete comme "toto" suivi par le developpement de la variable "truc". Si la valeur est true ou on, "toto$truc" est un nom unique de sept caracteres et les variables d'expansion doivent etre specifiees avec des accolades ou des parentheses. .pragma [=] includedir:valeur Si un chemin relatif est specifie dans la directive .include et si la variable d'environnement OPENSSL_CONF_INCLUDE n'existe pas, la valeur de la directive includedir, si elle existe, est ajoutee au debut du chemin. Parametres Un fichier de configuration est divise en plusieurs sections. Une section commence par le nom de section entre crochets et se termine quand une autre section commence ou quand la fin du fichier est atteinte. Le nom de section peut contenir des caracteres alphanumeriques et des caracteres de soulignement. Les espaces entre le nom et les crochets sont supprimes. La premiere section d'un fichier de configuration est speciale et est appelee la section par defaut (<< default >>), qui n'est generalement pas nommee et commence au debut du fichier jusqu'a la premiere section nommee. Quand un nom est recherche, il est d'abord recherche dans la section en cours ou la section nommee, puis dans la section par defaut. L'environnement est projete dans une section appelee ENV. Une section conporte une serie d'assignations nom/valeur decrites plus en detail ci-dessous. Pour rappel, les crochets presents dans cet exemple sont obligatoires et non optionnels. [ section ] nom_1 = valeur_1 nom_2 = autre_valeur ... [ nouvelle section ] nom_1 = nouvelle valeur_1 nom_3 = valeur_3 La chaine nom peut contenir des caracteres alphanumeriques ainsi que quelques symboles de ponctuation comme , . ; et _. L'espace apres le nom et celui avant le signe egal sont ignores. Si le meme nom existe dans la meme section, toutes les valeurs sauf la derniere seront ignorees. Dans certaines circonstances telles qu'avec les noms uniques de certificat (<< Certificate DN >>), le meme champ peut apparaitre plusieurs fois. Afin de gerer cela, les commandes telles que openssl-req(1) ignorent tout texte initial precede par un point .. Par exemple : 1.OU = Premier OU 2.OU = Second OU La chaine valeur est composee de la chaine qui suit le caractere = jusqu'a la fin de la ligne avec tous les espaces de debut et de fin supprimes. La chaine de la valeur est soumise a l'extension de variable. Le texte $var ou "${var}"' insere la valeur de la variable nommee a partir de la section en cours. Pour utiliser une valeur venant d'une autre section, utilisez $section::nom ou "${section::nom}". En utilisant $ENV::nom, la valeur de la variable d'environnement specifiee sera substituee. Les variables doivent etre definies avant le referencement de leur valeur, autrement une erreur est signalee et le fichier n'est pas charge. Cela peut etre contourne en specifiant une valeur par defaut dans la section par defaut (<< default section >>) avant l'utilisation de la variable. Tout parametre nom/valeur dans une section ENV est disponible pour le fichier de configuration, mais ne se propage pas dans l'environnement. C'est une erreur si la valeur finit par avoir une longueur superieure a 64 Ko. Certains caracteres peuvent etre proteges a l'aide d'un guillemet simple ' ou double " autour de la valeur, ou du caractere barre oblique inversee \ avant le caractere. Si le dernier caractere d'une ligne est \, une chaine valeur peut etre repartie sur plusieurs lignes. De plus, les suites \n, \r, \b et \t sont reconnues. Les regles d'expansion et de protection telles que decrites ci-dessus pour valeur s'appliquent aussi au chemin de la directive .include. CONFIGURATION DE LA BIBLIOTHEQUE OPENSSL Les sections ci-dessous utilisent le terme informel de module pour faire reference a une partie des fonctions d'OpenSSL. Cette appellation n'est pas identique au terme formel module FIPS, par exemple. La configuration d'OpenSSL recherche la valeur d'openssl_conf dans la section par defaut et la prend comme nom de la section qui specifie comment configurer les modules dans la bibliotheque. Laisser un module dans sa configuration par defaut n'est pas une erreur. Une application peut specifier un nom different en appelant par exemple directement CONF_modules_load_file(). OpenSSL recherche aussi la valeur de config_diagnostics. Si elle existe et a une valeur numerique differente de zero, toute erreur supprimant les signaux passes a CONF_modules_load() sera ignoree. C'est utile pour diagnostiquer les erreurs de configuration mais son usage en production exige une attention supplementaire. Quand cette option est activee, une erreur de configuration empeche completement l'acces a un service. Sans cette option, et en presence d'une erreur de configuration, l'acces sera permis, mais la configuration souhaitee ne sera pas utilisee. # Ceci doit etre dans la section par defaut config_diagnostics = 1 openssl_conf = openssl_init [openssl_init] oid_section = oid providers = fournisseurs alg_section = evp_properties ssl_conf = ssl_configuration engines = moteurs random = alea [oid] ... nouveaux oid ... [providers] ... choses concernant le fournisseur ... [evp_properties] ... proprietes d'EVP ... [ssl_configuration] ... proprietes de la configuration SSL/TLS ... [engines] ... proprietes du moteur ... [random] ... proprietes de l'alea ... La semantique de chacun des modules est decrite ci-dessous. La phrase << dans la section d'initialisation >> fait reference a la section identifiee par openssl_conf ou un autre nom (comme openssl_init dans l'exemple ci-dessus). Les exemples ci-dessous partent du principe que la configuration ci-dessus est utilisee pour specifier les sections individuelles. Configuration de l'identifiant d'objet ASN.1 Le nom oid_section dans la section d'initialisation designe la section qui fournit les paires nom/valeur des identifiants d'objet (<< OID >>). Le nom est le nom court ; la valeur est un nom long facultatif suivi d'une virgule et de la valeur numerique. Meme si certaines commandes OpenSSL possedent leur propre section pour specifier les OID, cette section les rend disponibles pour la totalite des commandes et des applications. [oid] shortName = un tres long nom d'oid = 1.2.3.4 nouvel_oid = 1.2.3.4 un_autre_oid = 1.2.3.5 Si une configuration complete comprenant le fragment ci-dessus est dans le fichier exemple.cnf, la ligne de commande suivante : OPENSSL_CONF=exemple.cnf openssl asn1parse -genstr OID:1.2.3.4.1 produira : 0:d=0 hl=2 l= 4 prim: OBJECT :nouvel_oid1 montrant que l'OID << nouvel_oid1 >> a ete ajoute en tant que << 1.2.3.4.1 >>. Configuration de fournisseur Le nom providers dans la section d'initialisation designe la section qui contient la configuration du fournisseur de chiffrement. Chacune des affectations nom/valeur dans cette section designe un fournisseur et pointe vers la section de configuration correspondante. La section specifique au fournisseur est utilisee pour indiquer comment charger le module, l'activer et definir d'autres parametres. Dans la section fournisseur, les noms suivants signifient : identity Cela est utilise pour specifier un nom alternatif qui outrepasse le nom par defaut specifie dans la liste des fournisseurs, par exemple : [providers] toto = fournisseur_toto [fournisseur_toto] identity = mon_module_fips module Specifie le chemin du module a charger (habituellement une bibliotheque partagee). activate S'il est present, le module est active. La valeur affectee a ce nom n'a pas de signification. Tous les parametres dans la section ainsi que dans les sous-sections sont disponibles pour le fournisseur. Le fournisseur par defaut et son activation Si aucun fournisseur n'est active explicitement, celui par defaut le sera implicitement. Voir OSSL_PROVIDER-default(7) pour plus de details. Si vous ajoutez une section qui active explicitement un ou plusieurs autres fournisseurs, vous aurez probablement a activer explicitement le fournisseur par defaut, sinon il devient non disponible dans openSSL. Cela peut rendre le systeme indisponible a distance. Configuration d'EVP Le nom alg_section dans la section d'initialisation designe la section qui contient les proprietes de l'algorithme lors de l'utilisation de l'API EVP. Dans la section de proprietes de l'algorithme, les noms suivants signifient : default_properties La valeur peut etre n'importe quelle valeur autorisee comme chaine de requete de propriete pour EVP_set_default_properties(). fips_mode (obsolete) La valeur est booleenne et peut etre yes ou no. Si la valeur est yes, c'est exactement l'equivalent de : default_properties = fips=yes Si la valeur est no, rien ne se passe. L'utilisation de ce nom est obsolete et, s'il est utilise, ce doit etre le seul nom de la section. Configuration de SSL Le nom ssl_conf dans la section d'initialisation designe la section qui contient la liste des configurations de SSL/TLS. Comme pour les fournisseurs, chaque nom dans cette section identifie une section avec la configuration correspondante. Par exemple : [ssl_configuration] server = server_tls_config client = client_tls_config system_default = tls_system_default [server_tls_config] ... configuration pour les serveurs SSL/TLS ... [client_tls_config] ... configuration pour les clients SSL/TLS ... Le nom de configuration system_default possede une signification particuliere. S'il existe, il est applique chaque fois qu'un objet SSL_CTX est cree. Par exemple, pour imposer au niveau du systeme des versions minimales des protocoles TLS et DTLS. [tls_system_default] MinProtocol = TLSv1.2 MinProtocol = DTLSv1.2 Le protocole minimal de TLS est applique aux objets 1SSL_CTX bases sur TLS et le protocole minimal de DTLS est applique a ceux qui sont bases sur DTLS. Il en est de meme pour les versions maximales definies par MaxProtocol. Chaque section de configuration est constituee de paires nom/valeur qui sont analysees par SSL_CONF_cmd(3) appele par SSL_CTX_config() ou SSL_config() de facon appropriee. Notez que tout caractere precedent un point initial dans la section de configuration est ignore, de maniere que la meme commande peut etre utilisee plusieurs fois. C'est probablement particulierement utile pour charger differents types de cle, comme ceci : [server_tls_config] RSA.Certificate = server-rsa.pem ECDSA.Certificate = server-ecdsa.pem Configuration du moteur Le nom engines dans la section d'initialisation designe la section qui contient la liste des configurations de MOTEUR. Comme pour les fournisseurs, chaque nom dans cette section identifie un moteur avec la configuration correspondante. La section specifique au moteur est utilisee pour indiquer comment charger le moteur, l'activer et definir d'autres parametres. Dans une section moteur, les noms suivants signifient : enabled_id Ce nom est utilise pour specifier un nom alternatif qui outrepasse le nom par defaut specifie dans la liste des moteurs. S'il est present, il doit etre en premier, par exemple : [engines] toto = moteur_toto [moteur_toto] engine_id = montoto dynamic_path Ce nom charge et ajoute un MOTEUR a partir du chemin donne. C'est equivalent a l'envoi des controles SO_PATH avec l'argument de chemin suivi par LIST_ADD avec la valeur 2 et LOAD au MOTEUR dynamique. Si ce n'est pas le comportement voulu, des controles alternatifs peuvent etre envoyes directement au MOTEUR dynamique en utilisant les commandes de controle. init Ce nom determine s'il faut initialiser le MOTEUR. Si la valeur est 0, le MOTEUR ne sera pas initialise ; si la valeur est 1, une tentative immediate d'initialiser le MOTEUR est realisee. Si la commande init n'est pas presente, alors une tentative d'initialiser le MOTEUR sera effectuee apres le traitement de toutes les commandes de la section. default_algorithms Ce nom definit les algorithmes par defaut qu'un MOTEUR fournira en utilisant la fonction ENGINE_set_default_string(). Tout autre nom est utilise pour nommer la commande de controle envoyee au MOTEUR et la valeur est l'argument passe a la commande. La valeur particuliere EMPTY signifie qu'aucune valeur n'est envoyee a la commande. Par exemple : [engines] toto = moteur_toto [moteur_toto] dynamic_path = /un/chemin/moteurtoto.so un_ctrl = une_valeur default_algorithms = ALL autre_ctrl = EMPTY Configuration de l'alea Le nom random dans la section d'initialisation designe la section contenant la configuration du generateur de nombres aleatoires. Dans la section alea, les noms suivants ont la signification : random Ce nom est utilise pour specifier le generateur de bits aleatoires, par exemple : [random] random = CTR-DRBG Les generateurs de bits aleatoires disponibles sont les suivants : CTR-DRBG HASH-DRBG HMAC-DRBG cipher Le nom choisi specifie le chiffrement un generateur de bits aleatoires CTR-DRBG utilisera. Les autres generateurs de bits aleatoires ignorent ce nom. La valeur par defaut est AES-256-CTR. digest Ce nom specifie quel condense les generateurs de bits aleatoires HASH-DRBG ou HMAC-DRBG utiliseront. Les autres generateurs de bits aleatoires ignorent ce nom. properties Ce nom definit la requete de propriete utilisee pour recuperer le generateur de bits aleatoires et les algorithmes sous-jacents. seed Ce nom definit la source d'alea a utiliser. Par defaut, SEED-SRC sera utilise en dehors du fournisseur FIPS. Le fournisseur FIPS utilise des rappels pour acceder aux memes sources d'alea en dehors des limites validees. seed-properties Ce nom definit la requete de propriete utilisee pour recuperer la source d'alea. EXEMPLES Cet exemple montre comment utiliser les guillemets et les echappements. # Ceci est la section par defaut. HOME = /temp configdir = $ENV::HOME/config [ premiere_section ] # Les guillemets permettent des espaces au debut et a la fin any = << n'importe quel nom de variable >> bidule = une chaine qui peut \ s'etendre sur plusieurs lignes \ en incluant \\ des caracteres message = Bonjour tout le monde\n [ deuxieme_section ] salutation = $premiere_section::message Cet exemple montre comment obtenir le developpement des variables d'environnement de facon sure. Dans l'exemple, la variable fichier_temporaire est censee se referer a un fichier temporaire, et la variable d'environnement TEMP ou TMP, si elle est presente, specifie le repertoire ou le fichier doit etre place. Dans la mesure ou la section par defaut est verifiee pour voir si la variable n'existe pas, il est possible de definir la valeur par defaut de TMP a /tmp et celle de TEMP a TMP. Ces deux lignes doivent etre dans la section par defaut. TMP = /tmp TEMP = $ENV::TMP # Cela peut etre utilise n'importe ou tmpfile = ${ENV::TEMP}/tmp.nom_fichier Cet exemple montre comment faire appliquer le mode FIPS pour l'application exemple. exemple = fips_config [fips_config] alg_section = evp_properties [evp_properties] default_properties = "fips=yes" ENVIRONNEMENT OPENSSL_CONF Le chemin vers le fichier de configuration ou une chaine vide pour aucun. Ignore dans les programmes set-user-ID et set-group-ID. OPENSSL_ENGINES Le chemin vers le repertoire des moteurs. Ignore dans les programmes set-user-ID et set-group-ID. OPENSSL_MODULES Le chemin vers le repertoire des modules OpenSSL tels que les fournisseurs (provider). Ignore dans les programmes set-user-ID et set-group-ID. OPENSSL_CONF_INCLUDE Le chemin optionnel a ajouter au debut de tous les chemins .include. BOGUES Rien ne permet d'inclure des caracteres a l'aide de la forme octale \nnn. Les chaines sont toutes terminees par NULL, donc NULL ne peut pas faire partie de la valeur. La protection par echappement n'est pas tout a fait correcte : si vous voulez utiliser des sequences d'echappement comme \n, vous ne pouvez pas utiliser de guillemets de protection sur la meme ligne. Le fait qu'un seul repertoire peut etre ouvert et lu a la fois peut etre considere comme un bogue et il devrait etre corrige. HISTORIQUE Une API non documentee, NCONF_WIN32(), utilisait un jeu de regles legerement differentes destinees a etre adaptees a la plateforme Windows de Microsoft. Plus precisement, le caractere barre oblique inversee n'etait pas un caractere d'echappement et pouvait etre utilise dans les chemins, seuls les guillemets doubles etaient reconnus et les commentaires commencaient par un point-virgule. Cette fonction est obsolete depuis OpenSSL 3.0 ; les applications avec des fichiers de configuration qui utilisent cette syntaxe doivent etre modifiees. VOIR AUSSI openssl-x509(1), openssl-req(1), openssl-ca(1), openssl-fipsinstall(1), ASN1_generate_nconf(3), EVP_set_default_properties(3), CONF_modules_load(3), CONF_modules_load_file(3), fips_config(5) et x509v3_config(5). COPYRIGHT Copyright 2000-2023 Les auteurs du projet OpenSSL. Tous droits reserves. Sous licence Apache 2.0 (la << Licence >>). Vous ne pouvez utiliser ce fichier que conformement avec la Licence. Vous trouverez une copie dans le fichier LICENSE de la distribution du source ou a l'adresse . TRADUCTION La traduction francaise de cette page de manuel a ete creee par arne, tv, Montanes David , Nicolas Francois , David Prevot , Celia Boudjemai et Jean-Pierre Giraud Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . 3.2.1 30 janvier 2024 CONFIG(5ssl)