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

Installation

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.

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
1. Une ressource X.509 retournée par openssl_x509_read()
2. Une chaîne au format file://path/to/cert.pem; Le fichier ainsi repéré doit contenir un certificat, encodé au format PEM
3. Une chaîne contenant le contenu d'un certificat, encodé au format PEM.
Clés publiques/privées
1. Une ressource clé, retournée par la fonction openssl_get_publickey() ou openssl_get_privatekey()
2. Pour les clés publiques seulement : une ressource X.509
3. 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).
4. Une chaîne contenant une clé ou un certificat encodé au format PEM
5. 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

X509_PURPOSE_SSL_CLIENT (entier)
X509_PURPOSE_SSL_SERVER (entier)
X509_PURPOSE_NS_SSL_SERVER (entier)
X509_PURPOSE_SMIME_SIGN (entier)
X509_PURPOSE_SMIME_ENCRYPT (entier)
X509_PURPOSE_CRL_SIGN (entier)
X509_PURPOSE_ANY (entier)

Options de remplissage (`Padding`)

OPENSSL_PKCS1_PADDING (entier)
OPENSSL_SSLV23_PADDING (entier)
OPENSSL_NO_PADDING (entier)
OPENSSL_PKCS1_OAEP_PADDING (entier)

Types de clés

OPENSSL_KEYTYPE_RSA (entier)
OPENSSL_KEYTYPE_DSA (entier)
OPENSSL_KEYTYPE_DH (entier)

Constantes/options PKCS7

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.

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.

Ciphers

OPENSSL_CIPHER_RC2_40 (entier)
OPENSSL_CIPHER_RC2_128 (entier)
OPENSSL_CIPHER_RC2_64 (entier)
OPENSSL_CIPHER_DES (entier)
OPENSSL_CIPHER_3DES (entier)

Note : Ces constantes ont été ajoutées depuis PHP 4.3.0.

Constantes de version

OPENSSL_VERSION_TEXT (entier)
OPENSSL_VERSION_NUMBER (entier)

Note : Ces constantes ont été ajoutées depuis PHP 5.2.0.

Table des matières
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_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