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.
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 :
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.
