Cette extension utilise les fonctions de OpenSSL pour générer et vérifier les signatures, ainsi que pour sceller (chiffrer) et ouvrir (déchiffrer) les données. OpenSSL offre beaucoup de fonctionnalités que ce module n'offre pas actuellement. Quelques-unes pourront être ajoutées dans le futur.
Afin de pouvoir utiliser les fonctions OpenSSL, vous devez installer les fonctions OpenSSL. PHP depuis les version 4.0.5 et 4.3.1 fonctionnent avec openSSL >= 0.9.5. Les autres versions (PHP <=4.0.4pl1 et >= 4.3.2) nécessitent OpenSSL >= 0.9.6.
| Avertissement |
Vous êtes vivement encouragé à utiliser la version la plus récente d'OpenSSL afin d'éviter certaines vulnérabilités sur votre serveur web. |
Pour utiliser le support OpenSSL de PHP, vous devez aussi compiler PHP avec l'option de configuration --with-openssl[=DIR].
Note aux utilisateurs Win32 : Afin d'activer ce module dans l'environnement Windows, vous devez copier les bibliothèques libeay32.dll depuis le dossier DLL de PHP/Win32 dans le dossier système SYSTEM32 de votre machine (par exemple : C:\WINNT\SYSTEM32 ou C:\WINDOWS\SYSTEM32).
De plus, si vous envisagez de générer des clés et de signer des messages, vous devez installer un fichier openssl.cnf valide sur votre système. Depuis PHP 4.3.0, une configuration simple est incluse dans le dossier openssl de la distribution Windows. Si vous utilisez PHP PHP 4.2.0 ou plus ancien, et que ces fichiers manquent, vous pouvez les télécharger sur le site d'OpenSSL ou en téléchargeant les fichiers de configuration de PHP 4.3.0.
Note aux utilisateurs Win32 : PHP va rechercher le fichier openssl.cnf suivant la tactique suivante :
La variable d'environnement OPENSSL_CONF, si elle est définie, sera utilisée comme chemin (comprenant le fichier) vers le fichier de configuration.
La variable d'environnement SSLEAY_CONF, si elle est définie, sera utilisée comme chemin (comprenant le fichier) vers le fichier de configuration.
Le fichier openssl.cnf sera supposé se trouver dans le dossier des certificats, tel que configuré lors de la compilation de la bibliothèque openssl. Cela signifie généralement c:\usr\local\ssl\openssl.cnf.
Dans votre installation, vous devrez décider si vous allez installer le fichier dans c:\usr\local\ssl\openssl.cnf ou si vous allez le faire ailleurs et configurer une variable d'environnement (possiblement par site virtuel). Notez qu'il est possible de remplacer le chemin par défaut en utilisant le paramètre configargs des fonctions qui requièrent un fichier de configuration.
Cette extension ne définit aucune directive de configuration.
Un bon nombre de fonctions OpenSSL demandent une clé et un certificat comme paramètres. PHP 4.0.5 et plus récent utilisait des clés ou certificats sous forme de ressource, retournée par l'une des fonctions openssl_get_xxx(). Les versions ultérieures utilisent l'une des méthodes suivantes :
Certificats
Une ressource X.509 retournée par openssl_x509_read()
Une chaîne au format file://path/to/cert.pem; Le fichier ainsi repéré doit contenir un certificat, encodé au format PEM
Une chaîne contenant le contenu d'un certificat, encodé au format PEM.
Clés publiques/privées
Une ressource clé, retournée par la fonction openssl_get_publickey() ou openssl_get_privatekey()
Pour les clés publiques seulement : une ressource X.509
Une chaîne avec le format : file://path/to/file.pem. Le fichier doit contenir une clé privée, ou un certificat, encodé au format PEM (il peut contenir les deux).
Une chaîne contenant une clé ou un certificat encodé au format PEM
Pour les clés privées, vous pouvez aussi utiliser la syntaxe array($key, $passphrase), où $key représente une clé spécifiée par un fichier ou une représentation textuelle comme cité ci-dessus, et $passphrase représente une chaîne contenant la passe-phrase de cette clé privée.
Lorsque vous appelez une fonction qui va vérifier une signature ou un certificat, le paramètre cainfo doit être un tableau contenant les noms d'un dossier et d'un fichier indiquant les tiers de confiance. Si un dossier est spécifié, il doit être correct, car openssl va l'utiliser.
Ces constantes sont définies par cette extension, et ne sont disponibles que si cette extension a été compilée avec PHP, ou bien chargée au moment de l'exécution.
Les fonctions S/MIME utilisent des options qui sont spécifiées par un champ de bits. Les valeurs valides sont :
Tableau 1. Constantes PKCS7
| Constante | Description |
|---|---|
| PKCS7_TEXT | Ajoute le texte plein en clair dans les en-têtes du message signé/chiffré. Lors du déchiffrement ou la vérification, il supprime purement et simplement ces données. Si le message chiffré ou signé n'est pas du type MIME, une erreur surviendra. |
| PKCS7_BINARY | Normalement, le message est converti au format canonique qui utilise effectivement des CR et LF comme fin de ligne, comme demandé dans les spécifications de S/MIME. Lorsque cette option est activée, le message ne sera pas converti. Cela sert lorsque vous manipulez des données binaires qui ne sont pas au format MIME. |
| PKCS7_NOINTERN | Lors de la vérification d'un message, les certificats (s'il y en a) inclus dans le message sont normalement utilisés pour rechercher le certificat de signature. Avec cette option, seul le certificat spécifié par le paramètre extracerts de la fonction openssl_pkcs7_verify() est utilisé. Les certificats fournis peuvent toujours être utilisés, avec un niveau de confiance réduit. |
| PKCS7_NOVERIFY | Ne vérifie pas les certificats des signataires d'un message signé. |
| PKCS7_NOCHAIN | N'enchaîne pas les vérifications des signataires de certificats. C'est-à-dire, n'utilise pas les certificats contenu dans le message. |
| PKCS7_NOCERTS | Lors de la signature d'un message, le certificat du signataire est normalement inclus. Avec cette option, c'est désactivé. Cela va réduire la taille du message, mais le vérificateur devra avoir une copie locale du certificat du signataire (passée au paramètre extracerts, avec la fonction openssl_pkcs7_verify()). |
| PKCS7_NOATTR | Normalement, lorsqu'un message est signé, un jeu d'attributs contenant l'heure de signature et l'algorithme symétrique supporté, est inclus dans le message. Avec cette option, il n'est pas inclus. |
| PKCS7_DETACHED | Lors de la signature d'un message, utilise la signature en texte clair, avec le type MIME "multipart/signed". C'est la valeur par défaut du paramètre flags pour la fonction openssl_pkcs7_sign(). Si vous annulez cette option, le message sera signé de manière opaque, ce qui résiste mieux à la traduction des relais emails (certains serveurs mail anciens corrompent les messages), mais empêche la lecture par les client emails qui ne connaissent pas S/MIME. |
| PKCS7_NOSIGS | Ne vérifie pas les signatures d'une message |
Note : Ces constantes ont été ajoutées en PHP 4.0.6.
| Précédent | Sommaire | Suivant |
| openal_stream | Niveau supérieur | openssl_csr_export_to_file |