Ubuntu Manpage: config — Fichiers de configuration de la bibliothèque OpenSSL CONF

NOM

       config — Fichiers de configuration de la bibliothèque OpenSSL CONF

DESCRIPTION

       Cette page documente la syntaxe des fichiers de configuration d'OpenSSL tels qu'ils sont analysés par
       NCONF_load(3) et les fonctions liées. Ce format est utilisé par de nombreuses commandes d'OpenSSL, ainsi
       que pour initialiser les bibliothèques lors de leur utilisation par une application.

       La première partie décrit la syntaxe générale des fichiers de configuration et les sections suivantes
       décrivent les sémantiques des modules individuels. D'autres modules sont décrits dans fips_config(5) et
       x509v3_config(5). La syntaxe de la définition des valeurs d'ASN.1 est décrite dans
       ASN1_generate_nconf(3).

SYNTAXE

Un fichier de configuration est une série de lignes. Les lignes blanches et les espaces entre les
éléments d'une ligne n'ont pas de signification. Un commentaire débute par le caractère # ; le reste de
la ligne est ignoré. Si le # est le premier caractère (qui n'est pas un espace) dans une ligne, la ligne
entière est ignorée.

Directives
Deux directives, .include et .pragma peuvent être utilisées pour contrôler l'analyse des fichiers de
configuration.

Pour assurer une compatibilité avec les versions plus anciennes d'OpenSSL, un signe égal après la
directive est ignoré. Les versions plus anciennes le traitent comme une affectation, aussi il faut
prendre des précautions si la différence dans les sémantiques 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 à cet emplacement. Les fichiers inclus
peuvent avoir des affectations .include qui spécifient d'autres fichiers. Si chemin est un répertoire,
tous les fichiers dans ce répertoire qui possèdent l'extension ".cnf" ou ".conf" seront inclus,
(disponible seulement dans les systèmes qui gèrent les entrées-sorties POSIX). Les sous-directoires
trouvés dans le chemin sont ignorés. De la même façon, si un fichier est ouvert pendant le balayage d'un
répertoire et si ce fichier contient une directive .include qui spécifie un répertoire, elle est aussi
ignorée.

Comme règle générale, le chemin devrait être un chemin absolu ; cela peut être imposé avec les directives
abspath et includedir décrites plus loin. La variable d'environnement OPENSSL_CONF_INCLUDE, si elle
existe, est ajoutée au début de tous les chemins relatifs. Si le chemin est encore relatif, il est
interprété par rapport au répertoire de travail en cours.

Pour obliger toutes les inclusions de fichier à nommer des chemins absolus, utilisez la directive
suivante :

.pragma [=] abspath:valeur

Le comportement par défaut, où 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 utilisé pour référencer une variable, comme décrit ci-dessous.
Sur certaines plateformes, néanmoins, il est courant de traiter $ comme un caractère normal dans les noms
de symbole. La prise en charge de ce comportement peut être obtenu avec la directive suivante :

.pragma [=] dollarid:valeur

Le comportement par défaut, où la valeur est false ou off, est de traiter le signe dollar comme
l'indication d'un nom de variable ; "toto$truc"' est interprété comme "toto" suivi par le développement
de la variable "truc". Si la valeur est true ou on, "toto$truc" est un nom unique de sept caractères et
les variables d'expansion doivent être spécifiées avec des accolades ou des parenthèses.

.pragma [=] includedir:valeur

Si un chemin relatif est spécifié 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 ajoutée au
début du chemin.

Paramètres
Un fichier de configuration est divisé 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 caractères alphanumériques et des caractères de soulignement. Les
espaces entre le nom et les crochets sont supprimés.

La première section d'un fichier de configuration est spéciale et est appelée la section par défaut
(« default »), qui n’est généralement pas nommée et commence au début du fichier jusqu'à la première
section nommée. Quand un nom est recherché, il est d'abord recherché dans la section en cours ou la
section nommée, puis dans la section par défaut.

L'environnement est projeté dans une section appelée ENV.

Une section conporte une série d'assignations nom/valeur décrites plus en détail ci-dessous. Pour rappel,
les crochets présents 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 chaîne nom peut contenir des caractères alphanumériques ainsi que quelques symboles de ponctuation
comme , . ; et _. L'espace après le nom et celui avant le signe égal sont ignorés.

Si le même nom existe dans la même section, toutes les valeurs sauf la dernière seront ignorées. Dans
certaines circonstances telles qu'avec les noms uniques de certificat (« Certificate DN »), le même champ
peut apparaître plusieurs fois. Afin de gérer cela, les commandes telles que openssl-req(1) ignorent tout
texte initial précédé par un point .. Par exemple :

1.OU = Premier OU 2.OU = Second OU

La chaîne valeur est composée de la chaîne qui suit le caractère = jusqu'à la fin de la ligne avec tous
les espaces de début et de fin supprimés.

La chaîne de la valeur est soumise à l'extension de variable. Le texte $var ou "${var}"' insère la valeur
de la variable nommée à 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 spécifiée sera substituée.

Les variables doivent être définies avant le référencement de leur valeur, autrement une erreur est
signalée et le fichier n'est pas chargé. Cela peut être contourné en spécifiant une valeur par défaut
dans la section par défaut (« default section ») avant l'utilisation de la variable.

Tout paramètre 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 supérieure à 64 Ko.

Certains caractères peuvent être protégés à l'aide d'un guillemet simple ' ou double " autour de la
valeur, ou du caractère barre oblique inversée \ avant le caractère. Si le dernier caractère d'une ligne
est \, une chaîne valeur peut être répartie sur plusieurs lignes. De plus, les suites \n, \r, \b et \t
sont reconnues.

Les règles d'expansion et de protection telles que décrites ci-dessus pour valeur s'appliquent aussi au
chemin de la directive .include.

CONFIGURATION DE LA BIBLIOTHÈQUE OPENSSL

Les sections ci-dessous utilisent le terme informel de module pour faire référence à 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 défaut et la prend
comme nom de la section qui spécifie comment configurer les modules dans la bibliothèque. Laisser un
module dans sa configuration par défaut n'est pas une erreur. Une application peut spécifier un nom
différent en appelant par exemple directement CONF_modules_load_file().

OpenSSL recherche aussi la valeur de config_diagnostics. Si elle existe et a une valeur numérique
différente de zéro, toute erreur supprimant les signaux passés à CONF_modules_load() sera ignorée. C'est
utile pour diagnostiquer les erreurs de configuration mais son usage en production exige une attention
supplémentaire. Quand cette option est activée, une erreur de configuration empêche complètement l'accès
à un service. Sans cette option, et en présence d'une erreur de configuration, l'accès sera permis, mais
la configuration souhaitée ne sera pas utilisée.

# Ceci doit être dans la section par défaut 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 = aléa [oid]
... nouveaux oid ... [providers] ... choses concernant le
fournisseur ... [evp_properties] ... propriétés d'EVP ...
[ssl_configuration] ... propriétés de la configuration SSL/TLS ...
[engines] ... propriétés du moteur ... [random] ... propriétés
de l'aléa ...

La sémantique de chacun des modules est décrite ci-dessous. La phrase « dans la section
d'initialisation » fait référence à la section identifiée 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 utilisée pour spécifier les sections individuelles.

Configuration de l'identifiant d'objet ASN.1
Le nom oid_section dans la section d'initialisation désigne 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 numérique. Même si certaines commandes OpenSSL possèdent leur propre
section pour spécifier les OID, cette section les rend disponibles pour la totalité des commandes et des
applications.

[oid] shortName = un très long nom d'oid = 1.2.3.4 nouvel_oid =
1.2.3.4 un_autre_oid = 1.2.3.5

Si une configuration complète 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 été ajouté en tant que « 1.2.3.4.1 ».

Configuration de fournisseur
Le nom providers dans la section d'initialisation désigne la section qui contient la configuration du
fournisseur de chiffrement. Chacune des affectations nom/valeur dans cette section désigne un fournisseur
et pointe vers la section de configuration correspondante. La section spécifique au fournisseur est
utilisée pour indiquer comment charger le module, l'activer et définir d'autres paramètres.

Dans la section fournisseur, les noms suivants signifient :

identity
Cela est utilisé pour spécifier un nom alternatif qui outrepasse le nom par défaut spécifié dans la
liste des fournisseurs, par exemple :

[providers] toto = fournisseur_toto [fournisseur_toto]
identity = mon_module_fips

module
Spécifie le chemin du module à charger (habituellement une bibliothèque partagée).

activate
S'il est présent et défini à une des valeurs yes, on, true ou 1, le fournisseur associé sera activé.
À l'inverse, définir cette valeur à no, off, false ou 0 empêchera l'activation du fournisseur. Les
réglages peuvent être donnés en minuscule ou en capitale. Définir activate à une autre valeur ou
omettre une valeur de réglage aboutira à une erreur.

= item soft_load

If enabled, informs the library to clear the error stack on failure to activate requested provider. A
value of 1, yes, true or on (in lower or uppercase) will activate this setting, while a value of 0,
no, false, or off (again in lower or uppercase) will disable this setting. Any other value will
produce an error. Note this setting defaults to off if not provided

Tous les paramètres dans la section ainsi que dans les sous-sections sont disponibles pour le
fournisseur.

Le fournisseur par défaut et son activation

Si aucun fournisseur n'est activé explicitement, celui par défaut le sera implicitement. Voir
OSSL_PROVIDER-default(7) pour plus de détails.

Si vous ajoutez une section qui active explicitement un ou plusieurs autres fournisseurs, vous aurez
probablement à activer explicitement le fournisseur par défaut, sinon il devient non disponible dans
openSSL. Cela peut rendre le système indisponible à distance.

Configuration d'EVP
Le nom alg_section dans la section d'initialisation désigne la section qui contient les propriétés de
l'algorithme lors de l'utilisation de l'API EVP.

Dans la section de propriétés de l'algorithme, les noms suivants signifient :

default_properties
La valeur peut être n'importe quelle valeur autorisée comme chaîne de requête de propriété pour
EVP_set_default_properties().

fips_mode (obsolète)
La valeur est booléenne et peut être yes ou no. Si la valeur est yes, c'est exactement l'équivalent
de :

default_properties = fips=yes

Si la valeur est no, rien ne se passe. L'utilisation de ce nom est obsolète et, s'il est utilisé, ce
doit être le seul nom de la section.

Configuration de SSL
Le nom ssl_conf dans la section d'initialisation désigne 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 possède une signification particulière. S'il existe, il est
appliqué chaque fois qu'un objet SSL_CTX est créé. Par exemple, pour imposer au niveau du système des
versions minimales des protocoles TLS et DTLS.

[tls_system_default] MinProtocol = TLSv1.2 MinProtocol = DTLSv1.2

Le protocole minimal de TLS est appliqué aux objets 1SSL_CTX basés sur TLS et le protocole minimal de
DTLS est appliqué à ceux qui sont basés sur DTLS. Il en est de même pour les versions maximales définies
par MaxProtocol.

Chaque section de configuration est constituée de paires nom/valeur qui sont analysées par
SSL_CONF_cmd(3) appelé par SSL_CTX_config() ou SSL_config() de façon appropriée. Notez que tout caractère
précédent un point initial dans la section de configuration est ignoré, de manière que la même commande
peut être utilisée plusieurs fois. C'est probablement particulièrement utile pour charger différents
types de clé, 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 désigne 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 spécifique au moteur est utilisée pour indiquer comment
charger le moteur, l'activer et définir d'autres paramètres.

Dans une section moteur, les noms suivants signifient :

enabled_id
Ce nom est utilisé pour spécifier un nom alternatif qui outrepasse le nom par défaut spécifié dans la
liste des moteurs. S'il est présent, il doit être en premier, par exemple :

[engines] toto = moteur_toto [moteur_toto] engine_id =
montoto

dynamic_path
Ce nom charge et ajoute un MOTEUR à partir du chemin donné. C'est équivalent à l'envoi des contrôles
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 contrôles alternatifs peuvent être envoyés directement au
MOTEUR dynamique en utilisant les commandes de contrôle.

init
Ce nom détermine s'il faut initialiser le MOTEUR. Si la valeur est 0, le MOTEUR ne sera pas
initialisé ; si la valeur est 1, une tentative immédiate d’initialiser le MOTEUR est réalisée. Si la
commande init n'est pas présente, alors une tentative d’initialiser le MOTEUR sera effectuée après le
traitement de toutes les commandes de la section.

default_algorithms
Ce nom définit les algorithmes par défaut qu’un MOTEUR fournira en utilisant la fonction
ENGINE_set_default_string().

Tout autre nom est utilisé pour nommer la commande de contrôle envoyée au MOTEUR et la valeur est
l'argument passé à la commande. La valeur particulière EMPTY signifie qu'aucune valeur n'est envoyée à 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'aléa
Le nom random dans la section d'initialisation désigne la section contenant la configuration du
générateur de nombres aléatoires.

Dans la section aléa, les noms suivants ont la signification :

random
Ce nom est utilisé pour spécifier le générateur de bits aléatoires, par exemple :

[random] random = CTR-DRBG

Les générateurs de bits aléatoires disponibles sont les suivants :

CTR-DRBG
HASH-DRBG
HMAC-DRBG
cipher
Le nom choisi spécifie le chiffrement un générateur de bits aléatoires CTR-DRBG utilisera. Les autres
générateurs de bits aléatoires ignorent ce nom. La valeur par défaut est AES-256-CTR.

digest
Ce nom spécifie quel condensé les générateurs de bits aléatoires HASH-DRBG ou HMAC-DRBG utiliseront.
Les autres générateurs de bits aléatoires ignorent ce nom.

properties
Ce nom définit la requête de propriété utilisée pour récupérer le générateur de bits aléatoires et
les algorithmes sous-jacents.

seed
Ce nom définit la source d'aléa à utiliser. Par défaut, SEED-SRC sera utilisé en dehors du
fournisseur FIPS. Le fournisseur FIPS utilise des rappels pour accéder aux mêmes sources d'aléa en
dehors des limites validées.

seed-properties
Ce nom définit la requête de propriété utilisée pour récupérer la source d'aléa.

EXEMPLES

       Cet exemple montre comment utiliser les guillemets et les échappements.

        # Ceci est la section par défaut.  HOME = /temp  configdir =
       $ENV::HOME/config   [ première_section ]  # Les guillemets permettent
       des espaces au début et à la fin  any = « n'importe quel nom de variable »
        bidule = une chaîne qui peut \  s'étendre sur plusieurs lignes \
       en incluant \\ des caractères  message = Bonjour tout le monde\n
       [ deuxième_section ]  salutation = $première_section::message

       Cet exemple montre comment obtenir le développement des variables d'environnement  de  façon  sûre.  Dans
       l'exemple,  la  variable fichier_temporaire est censée se référer à un fichier temporaire, et la variable
       d'environnement TEMP ou TMP, si elle est présente, spécifie le répertoire où le fichier doit être  placé.
       Dans  la  mesure  où  la  section  par  défaut est vérifiée pour voir si la variable n'existe pas, il est
       possible de définir la valeur par défaut de TMP à /tmp et celle de TEMP à TMP.

       Ces deux lignes doivent être dans la section par défaut.  TMP = /tmp
       TEMP = $ENV::TMP   # Cela peut être utilisé n'importe où  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 chaîne vide pour aucun. Ignoré dans les  programmes
           set-user-ID et set-group-ID.

       OPENSSL_ENGINES
           Le chemin vers le répertoire des moteurs. Ignoré dans les programmes set-user-ID et set-group-ID.

       OPENSSL_MODULES
           Le  chemin  vers  le répertoire des modules OpenSSL tels que les fournisseurs (provider). Ignoré dans
           les programmes set-user-ID et set-group-ID.

       OPENSSL_CONF_INCLUDE
           Le chemin optionnel à ajouter au début de tous les chemins .include.

BOGUES

       Rien ne permet d'inclure des caractères à l'aide de  la  forme  octale  \nnn.  Les  chaînes  sont  toutes
       terminées par NULL, donc NULL ne peut pas faire partie de la valeur.

       La  protection  par  échappement  n'est  pas tout à fait correcte : si vous voulez utiliser des séquences
       d'échappement comme \n, vous ne pouvez pas utiliser de guillemets de protection sur la même ligne.

       Le fait qu'un seul répertoire peut être ouvert et lu à la fois peut être considéré comme un bogue  et  il
       devrait être corrigé.

HISTORIQUE

       Une API non documentée, NCONF_WIN32(), utilisait un jeu de règles légèrement différentes destinées à être
       adaptées  à  la  plateforme  Windows  de Microsoft. Plus précisément, le caractère barre oblique inversée
       n'était pas un caractère d'échappement et pouvait être utilisé dans les  chemins,  seuls  les  guillemets
       doubles  étaient  reconnus  et  les  commentaires  commençaient  par un point-virgule. Cette fonction est
       obsolète depuis OpenSSL 3.0 ; les applications avec des fichiers de  configuration  qui  utilisent  cette
       syntaxe doivent être modifiées.

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-2025 The OpenSSL Project Authors. All Rights Reserved.

       Sous  licence  Apache  2.0  (la « Licence »). Vous ne pouvez utiliser ce fichier que conformément avec la
       Licence. Vous trouverez une copie dans le fichier LICENSE de la distribution du  source  ou  à  l'adresse
       <https://www.openssl.org/source/license.html>.

TRADUCTION

       La   traduction   française  de  cette  page  de  manuel  a  été  créée  par  arne,  tv,  Montanes  David
       <montanes.david@gmail.com>,   Nicolas   François   <nicolas.francois@centraliens.net>,    David    Prévot
       <david@tilapin.org>,    Celia    Boudjemai   <celisou2008@gmail.com>   et   Jean-Pierre   Giraud   <jean-
       pierregiraud@neuf.fr>

       Cette traduction est une documentation libre ; veuillez vous  reporter  à  la  GNU General Public License
       version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si  vous  découvrez  un  bogue  dans la traduction de cette page de manuel, veuillez envoyer un message à
       debian-l10n-french@lists.debian.org.

3.4.1                                            11 février 2025                                    CONFIG(5SSL)