OpenSSL
Introduction
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.
Pré-requis
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.4 et >= 4.3.2) nécessitent OpenSSL >= 0.9.6.
Vous êtes vivement encouragé à utiliser la version la plus récente d'OpenSSL afin d'éviter certaines vulnérabilités sur votre serveur web.
Installation
Pour utiliser le support OpenSSL de PHP, vous devez aussi compiler PHP avec l'option de configuration --with-openssl[=DIR].
Note: Note aux utilisateurs Win32 Afin de faire fonctionner cette extension, quelques bibliothèques DLL doivent être disponibles via le PATH du système Windows. Lisez la FAQ intitulée "Comment ajouter mon dossier PHP à mon PATH WIndows" pour plus d'informations. Le fait de copier les bibliothèques DLL depuis le dossier PHP dans le dossier système Windows fonctionne également (car le dossier système est par défaut dans le PATH système), mais cette méthode n'est pas recommandée. Cette extension nécessite que les fichiers suivants se trouvent dans le PATH : libeay32.dll
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. 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.
Configuration à l'exécution
Cette extension ne définit aucune directive de configuration.
Types de ressources
Paramètres clés/certificats
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.
Vérification de certificats
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.
Constantes pré-définies
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.
Options de validations générales
Options de remplissage (Padding)
Constantes/options PKCS7
Les fonctions S/MIME utilisent des options qui sont spécifiées par un champ de bits. Les valeurs valides sont :
| 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.
Algorithme de signature
- OPENSSL_ALGO_SHA1 (entier)
- Utilisé comme algorithme par défaut pour les fonctions openssl_sign() et openssl_verify().
- OPENSSL_ALGO_MD5 (entier)
- OPENSSL_ALGO_MD4 (entier)
- OPENSSL_ALGO_MD2 (entier)
Note: Ces constantes ont été ajoutées depuis PHP 5.0.0.
Table of Contents
- openssl_csr_export_to_file — Exporte une CSR vers un fichier
- openssl_csr_export — Exporte un CSR vers un fichier ou une variable
- openssl_csr_get_public_key — Retourne la clé publique d'un CERT
- openssl_csr_get_subject — Retourne le sujet d'un CERT
- openssl_csr_new — Génère une CSR
- openssl_csr_sign — Signe un CSR avec un autre certificat
- openssl_error_string — Retourne le message d'erreur OpenSSL
- openssl_free_key — Libère les ressources
- openssl_get_privatekey — Alias de openssl_pkey_get_private
- openssl_get_publickey — Alias de openssl_pkey_get_public
- openssl_open — Ouvre des données scellées
- openssl_pkcs12_export_to_file — Exports a PKCS#12 Compatible Certificate Store File
- openssl_pkcs12_export — Exports a PKCS#12 Compatible Certificate Store File to variable.
- openssl_pkcs12_read — Parse a PKCS#12 Certificate Store into an array
- openssl_pkcs7_decrypt — Déchiffre un message S/MIME
- openssl_pkcs7_encrypt — Chiffre un message S/MIME
- openssl_pkcs7_sign — Signe un message S/MIME
- openssl_pkcs7_verify — Vérifie la signature d'un message S/MIME
- openssl_pkey_export_to_file — Sauve une clé au format ASCII dans un fichier
- openssl_pkey_export — Lit une représentation exportable de la clé dans une chaîne ou un fichier
- openssl_pkey_free — Libère une clé privée
- openssl_pkey_get_details — Retourne un tableau contenant le détail des clés (bits, pkey, type)
- openssl_pkey_get_private — Lit une clé privée
- openssl_pkey_get_public — Extrait une clé privée d'un certificat, et la prépare
- openssl_pkey_new — Génère une nouvelle clé privée
- openssl_private_decrypt — Déchiffre des données avec une clé privée
- openssl_private_encrypt — Chiffre des données avec une clé privée
- openssl_public_decrypt — Déchiffre des données avec une clé publique
- openssl_public_encrypt — Chiffre des données avec une clé publique
- openssl_seal — Scelle des données
- openssl_sign — Signe les données
- openssl_verify — Vérifie une signature
- openssl_x509_check_private_key — Vérifie si une clé privée correspond à un certificat
- openssl_x509_checkpurpose — Vérifie l'usage d'un certificat
- openssl_x509_export_to_file — Exporte un certificat vers un fichier
- openssl_x509_export — Exporte un certificat vers une variable
- openssl_x509_free — Libère les ressources prises par un certificat
- openssl_x509_parse — Analyse un certificat X509
- openssl_x509_read — Analyse un certificat X.509 et retourne une ressource