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
The PHP OpenSSL extension provides a limited number of functions useful for manipulating X.509 certificates. The functions allow you to create and free a certificate resource, verify that a
certificate has permission to perform a specific function, and obtain information about the certificate. All certificate data that is provided to PHP must be PEM-encoded.
resource openssl_x509_readmixed certificate This function creates a certificate resource from X.509 certificate data. The certificate
data may be supplied as one of two representations: a string beginning with file: that contains the name of the file containing the certificate data, or a string containing 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 certificate is successfully loaded, the return will be a PHP resource for the certificate. When youre done using the certificate
resource, you should use
openssl_x509_free
to release it.
235
void openssl_x509_freeresource certificate This function releases a certificate resource that was previously obtained from
openssl_x509_read
. You should call this function to free any internal resources that are associated with a PHP certificate resource when you are through using it.
bool openssl_x509_checkpurposemixed certificate, int purpose, array cainfo [, string untrusted_file]
This function determines whether a certificate may be used to perform a specific function. The first argument,
certificate
, is a certificate resource obtained from
openssl_x509_read
. Table 9-1
lists the valid values for the second argument,
purpose
. Note that only one constant may be used at a time—the argument is not a bit mask. The third argument,
cainfo
, is a list of trusted certificate files or directories to be used in the verification of the certificate. If present, the optional argument,
untrusted_file
, is the name of the file containing any certificates of intermediate CAs required to verify the certificate. The extra certificates will not be trusted.
Table 9-1. Possible purpose values for openssl_x509_checkpurpose Constant Description
X509_PURPOSE_SSL_CLIENT
May the certificate be used for the client in an SSL session?
X509_PURPOSE_SSL_SERVER
May the certificate be used for the server in an SSL session?
X509_PURPOSE_NS_SSL_SERVER
May the certificate be used for a Netscape SSL server?
X509_PURPOSE_SMIME_SIGN
May the certificate be used for SMIME signing?
X509_PURPOSE_SMIME_ENCRYPT
May the certificate be used for SMIME encrypting?
X509_PURPOSE_CRL_SIGN
May the certificate be used to sign a certificate revocation list CRL?
X509_PURPOSE_ANY
May the certificate be used for any and all purposes? The
cainfo
array should contain a list of files that will be used to verify the certificate. Directories may also be included in the list. Files should contain one or more certificates,
and directories should contain certificates that would be accepted by the OpenSSL command-line tool commands that perform a similar function with the
CApath
option. Certificate files in a directory should contain one certificate per file and should be named
with the hash value of the certificate subjects name and an extension of .0. Any certificates made available via this function are trusted.
The return from this function will be true if the certificate may be used for the purpose that is being checked. If it may not, the return will be false. The integer value -1 will be
returned if an error occurs in the verification process;
openssl_error_string
should be used to obtain error information.
array openssl_x509_parsemixed certificate [, bool shortnames] This function returns information about a certificate in an associative array. The keys for
the array are currently undocumented, but easily discovered from the source code for the extension. Weve listed them here in
Table 9-2 ; however, due to the fact that they are
undocumented, if anything in the OpenSSL extension is going to change in future versions, these keys have a high probability. If you can avoid it, we would advise against
using this function for the time being until it stabilizes. If the second argument,
shortnames
, is omitted or specified as true, the keys in the returned array will use a shortened name.
236
Table 9-2. Keys for the array returned by openssl_x509_parse Key name
Data type
Description
name
string The name assigned to the certificate, if it has one. This key may not
be present.
subject
array An associative array that contains all of the fields comprising the
subjects distinguished name, such as
commonName
,
organizationName
, etc. The
shortnames
argument affects the keys in this array.
issuer
array An associative array that contains all of the fields comprising the
issuers distinguished name. The
shortnames
argument affects the keys in this array.
version
long The X.509
version.
serialNumber
long The certificates serial number.
validFrom
string A string representation of the date the certificate is valid from.
validTo
string A string representation of the date the certificate is valid to.
validFrom_time_t
long A
time_t
integer representation of the date the certificate is valid from number of seconds since Jan 1, 1970 00:00:00 GMT.
validTo_time_t
long A
time_t
integer representation of the date the certificate is valid to.
alias
string The alias assigned to the certificate, if it has one. This key may not
be present.
purposes
array Each element in this array represents a purpose that is supported by
OpenSSL. The index values of this array correspond to the constants listed in
Table 9-1 . Each element of that array is another
array containing three elements. The first two are bools. The first indicates whether the certificate may be used for that purpose, and
the second indicates whether the certificate is a CA. The third is a string representation of the purpose name, which is affected by the
shortnames
argument.
9.3.3 Encryption and Signing Functions
