SYNOPSIS

#include <openssl/x509.h>

int X509_check_host(X509 *, const char *name, size_t namelen,                  unsigned int flags, char **peername);

 int X509_check_email(X509 *, const char *address, size_t addresslen,                  unsigned int flags);

 int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen,                  unsigned int flags);

 int X509_check_ip_asc(X509 *, const char *address, unsigned int flags);

DESCRIPTION

Les fonctions de correspondance de certificats sont utilisées pour vérifier si un certificat correspond à un nom d'hôte, à une adresse courriel ou à une adresse IP. La validité du certificat et son niveau de confiance doivent être vérifiés par ailleurs.

X509_check_host() vérifie si le nom alternatif de sujet (SAN) ou le nom commun du sujet (CN) correspond au nom de domaine indiqué, encodé de préférence avec la syntaxe décrite dans la section 3.5 de la RFC 1034. Par défaut, les jokers sont acceptés et correspondent uniquement à la partie gauche de l'étiquette. Il peuvent cependant correspondre à une partie de l'étiquette qui aurait un préfixe ou un suffixe explicite. Par exemple, par défaut le nom de domaine name « www.example.com » correspondra à un certificat contenant le SAN ou le CN « *.example.com », « w*.example.com » ou « *w.example.com ».

Comme décrit dans la section 6.4.2 de la RFC 6125, les valeurs de name représentant des noms de domaines internationaux doivent être données sous la forme de A-label. L'argument namelen doit être le nombre de caractères dans la chaîne du nom, ou zéro et dans ce cas la longueur est calculée avec strlen(name). Lorsque name commence par un point, (comme dans « .example.com »), il correspondra à un certificat valable pour n'importe quel sous-domaine de name (voir aussi X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS ci-dessous).

Si le certificat correspond et que peername n'est pas NULL, un pointeur vers une copie du SAN ou CN correspondant du certificat du pair est stocké à l'adresse donnée dans peername. L'application est responsable de la libération du peername en utilisant OPENSSL_free() lorsque celui-ci n'est plus nécessaire.

X509_check_email() vérifie si le certificat correspond à l'adresse courriel indiquée dans address. Seule la syntaxe mailbox de la RFC 822 est prise en charge, les commentaires ne sont pas autorisés, et les caractères entre guillemets ne sont pas normalisés. L'argument addresslen doit être le nombre de caractères dans la chaîne de l'adresse, ou zéro et dans ce cas la longueur est calculée avec strlen(address).

X509_check_ip() vérifie si le certificat correspond à l'adresse IPv4 ou IPv6 indiquée. Le tableau address est au format binaire, dans l'ordre des octets du réseau (network byte order, grand-boutiste). La longueur peut être 4 (IPv4) ou 6 (IPv6). Seules les adresses explicitement indiquées dans les certificats sont prises en compte ; les adresses IP enregistrées dans les noms DNS et CN sont ignorées.

X509_check_ip_adsc() est identique, sauf que la chaîne address terminée par un caractère NULL est d'abord convertie dans sa représentation interne.

L'argument flags est généralement 0. Il peut être le OU logique des drapeaux suivants :

X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT,

X509_CHECK_FLAG_NO_WILDCARDS,

X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS,

X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS.

X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS.

Le drapeau X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT force la fonction à utiliser le nom de domaine du sujet même si le certificat contient un nom alternatif de sujet correct (nom DNS ou adresse courriel) ; le comportement par défaut est d'ignorer le nom de domaine du sujet lorsqu'au moins un nom alternatif de sujet est présent.

Si défini, X509_CHECK_FLAG_NO_WILDCARDS désactive l'expansion des jokers ; cela ne s'applique qu'à la fonction X509_check_host.

Si défini, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS désactive la prise en charge de « * » comme joker dans les étiquettes qui ont un préfixe ou un suffixe, comme « www* » ou « *www » ; cela ne s'applique qu'à la fonction X509_check_host.

Si défini, X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS autorise une « * » qui constitue une étiquette complète de nom DNS (comme dans « *.example.com ») à correspondre à plus d'une étiquette de name ; cela ne s'applique qu'à la fonction X509_check_host.

Si défini, X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS restreint les valeurs de name qui commencent par « . » et qui correspondraient à n'importe quel sous-domaine du certificat du pair, à correspondre uniquement aux sous-domaines enfants directs. Avec ce drapeau défini, un name défini à « .example.com » correspondra à un certificat contenant le nom DNS « www.example.com », mais pas « www.sub.example.com » ; cela ne s'applique qu'à la fonction X509_check_host.

VALEURS DE RETOUR

Les fonctions renvoient 1 en cas de correspondance, 0 s'il n'y en a pas, et -1 dans le cas d'une erreur interne : typiquement un échec d'allocation mémoire ou une erreur de décodage ASN.1.

Toutes les fonctions peuvent aussi renvoyer -2 si l'entrée est mal formée. Par exemple, X509_check_host() renvoie -2 si le name fourni contient des caractères NULL.

NOTES

Les applications sont encouragées à utiliser X509_VERIFY_PARAM_set1_host() plutôt que d'appeler X509_check_host(3). Les vérifications de noms de domaine ne sont plus requises avec l'utilisation des certificats DANE-EE(3), et les vérifications internes seront supprimées lorsque la prise en charge de DANE sera ajoutée à OpenSSL.

HISTORIQUE

Ces fonctions ont été ajoutées à OpenSSL 1.1.0.

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.