233
9.3 OpenSSL Support in PHP
PHP is a scripting language that is used primarily, if not exclusively, on the Web. It is normally HTML-embedded, although it is also capable of running as a CGI script. It boasts an extensive
library of functions that provide interfaces to a wide variety of common external libraries and services, such as LDAP and MySQL. PHP-4.04pl1 introduced experimental support for OpenSSL.
At the time of this writing, the current version of PHP is 4.1.1, and OpenSSL support is still considered experimental. Current versions of PHP require OpenSSL Version 0.9.5 or later.
Since PHPs support for OpenSSL is considered experimental, anything relating to the implementation could still change, including the function names, parameters, and return values.
The support for OpenSSL in PHP is more limited than Perl or Pythons support, but sufficient functionality does exist to make it moderately useful. Support for encryption, signing, SMIME,
key generation, and X.509 certificate manipulation is included.
PHPs OpenSSL functions are high-level abstractions from the OpenSSL API. Unlike Perl or Python, none of the low-level OpenSSL API is exposed directly. While this simplifies the usage of
OpenSSL greatly, it also restricts its capabilities. As newer versions of PHP have been released, new OpenSSL functionality has been introduced. We recommend that you use the latest version of
PHP available to you if you wish to make use of its OpenSSL functionality.
9.3.1 General Functions
The PHP OpenSSL extension provides four functions required for the more specific functionality offered by the extension. These functions provide a mechanism for error reporting as well as
private and public key management. In particular, many of the more specific functions require a public or private key, which are often supplied as a key resource. Key resources can be obtained
from any one of the sources listed below, but in all cases the key data obtained from an external source must be PEM-encoded because PHP provides no support for reading DER-encoded data:
•
The resource retreived from a prior call to either
openssl_get_publickey
or
openssl_get_privatekey •
An X.509 resource for public keys
•
A string that specifies a filename to read the key from
•
A string that contains the key data
•
An array that contains the key as a string representing a filename or containing the key data and the passphrase required to decrypt the key
In Version 4.0.5 or later of PHP, any of the inputs to
openssl_get_privatekey
,
openssl_get_publickey
, or
openssl_x509_read
, which return key or certificate resources, can be used as the key or certificate resource to the function requiring the key or
certificate resource. The earlier versions of the OpenSSL extension required the use of the three aforementioned functions, but versions that are more recent do not. If youll be using the same key
or certificate more than once, it is generally a good idea to use the functions to obtain a resource rather than obtaining it each time you need to use it.
mixed openssl_error_stringvoid This function pops the most recent error from OpenSSLs error stack and returns a string
representation of the error. If the stack is empty, the return from this function will be false. The string returned will be an English representation of the error as returned from the
OpenSSL function
ERR_error_string
. Note that OpenSSL pushes errors onto a stack, and that this function pops only one error from that stack. Call this function repeatedly
until it returns false in order to get all of the available error information when an error occurs.
234
resource openssl_get_privatekeymixed key [, string passphrase] This function creates a key resource for a private key. The first argument,
key
, can be one of three representations of a public key: a string beginning with file: that contains
the name of the file containing the private key data, a string that contains the private key data, or an array that contains the key information. If an array is used, the first element
should be either a string that contains the name of the file containing the key data, or the key data. The second element should be the passphrase to decrypt the key. The optional
argument,
passphrase
, should be a string containing the passphrase required to decrypt the key if one is necessary.
The return from this function is false if an error occurs;
openssl_error_string
should be used to obtain error information. If the key is successfully loaded and decrypted, the return will be a PHP resource for the key. When youre done using the key resource,
you should use
openssl_free_key
to release it. resource openssl_get_publickeymixed certificate
This function creates a key resource for a public key. The first argument,
key
, can be one of three representations of a certificate from which the public key will be extracted: a
certificate resource, a string beginning with file: that contains the name of the file containing the certificate data, or a string that contains the certificate data.
The return from this function is false if an error occurs;
openssl_error_string
should be used to obtain error information. If the key is successfully extracted from the certificate, the return will be a PHP resource for the key. When youre done using the key
resource, you should use
openssl_free_key
to release it. void openssl_free_keyresource key
This function releases a key resource that was previously obtained from either
openssl_get_privatekey
or
openssl_get_publickey
. You should call this function to free any internal resources that are associated with a PHP key resource when
you are through using it.
9.3.2 Certificate Functions
Kategori