mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
Added docs for new S/MIME functions plus more flexible keys/certs parameters.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@44769 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Wez Furlong
parent
2ad2ba0262
commit
6385ba9515
1 changed files with 627 additions and 13 deletions
|
|
@ -2,6 +2,8 @@
|
|||
<title>OpenSSL functions</title>
|
||||
<titleabbrev>OpenSSL</titleabbrev>
|
||||
<partintro>
|
||||
<sect1 id="openssl.intro">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
This module uses the functions of <ulink
|
||||
url="&url.openssl;">OpenSSL</ulink> for generation and verification
|
||||
|
|
@ -9,12 +11,206 @@
|
|||
data. PHP-4.0.4pl1 requires OpenSSL >= 0.9.6, but PHP-4.0.5 and greater
|
||||
with also work with OpenSSL >= 0.9.5.
|
||||
</para>
|
||||
<para>
|
||||
New for dev/CVS versions of PHP is support for S/MIME email
|
||||
signing/verification and encryption/decryption. Also, it is now possible
|
||||
to specify keys/certs in a vareity of ways that should help make your PHP
|
||||
code easier to write.
|
||||
These features will most likely make it into PHP 4.0.6.
|
||||
<emphasis>Please keep in mind that this extension is still considered
|
||||
experimental!</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
OpenSSL offers many features that this module currently doesn't support.
|
||||
Some of these may be added in the future.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="openssl.certparams">
|
||||
<title>Key/Certficate parameters</title>
|
||||
<para>
|
||||
Quite a few of the openssl functions require a key or a certificate
|
||||
parameter. PHP 4.0.5 and earlier have to use a key or certificate resource
|
||||
returned by one of the openssl_get_xxx functions. Later versions may use
|
||||
one of the following methods:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Certificates
|
||||
<orderedlist>
|
||||
<listitem><simpara>An X.509 resource returned from
|
||||
openssl_x509_read</simpara></listitem>
|
||||
<listitem><simpara>A string having the format
|
||||
<filename>file://path/to/cert.pem</filename>; the named file must
|
||||
contain a PEM encoded certificate</simpara></listitem>
|
||||
<listitem><simpara>A string containing the content of a certificate,
|
||||
PEM encoded</simpara></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Public/Private Keys
|
||||
<orderedlist>
|
||||
<listitem><simpara>A key resource returned from
|
||||
<function>openssl_get_publickey</function> or
|
||||
<function>openssl_get_privatekey</function></simpara></listitem>
|
||||
<listitem><simpara>For public keys only: an X.509
|
||||
resource</simpara></listitem>
|
||||
<listitem><simpara>A string having the format
|
||||
<filename>file://path/to/file.pem</filename> - the named file must
|
||||
contain a PEM encoded certificate/private key (it may contain
|
||||
both)</simpara></listitem>
|
||||
<listitem><simpara>A string containing the content of a
|
||||
certificate/key, PEM encoded</simpara></listitem>
|
||||
<listitem><simpara>For private keys, you may also use the syntax
|
||||
<emphasis>array($key, $passphrase)</emphasis> where $key represents a
|
||||
key specified using the file:// or textual content notation above, and
|
||||
$passphrase represents a string containing the passphrase for that
|
||||
private key</simpara></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="openssl.cert.verification">
|
||||
<title>Certificate Verification</title>
|
||||
<para>
|
||||
When calling a function that will verify a signature/certificate, the
|
||||
<emphasis>cainfo</emphasis> parameter is an array containing file and
|
||||
directory names the specify the locations of trusted CA files. If a
|
||||
directory is specified, then it must be a correctly formed hashed directory
|
||||
as the <command>openssl</command> command would use.
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="openssl.pkcs7.flags">
|
||||
<title>PKCS7 Flags/Constants</title>
|
||||
<para>
|
||||
The S/MIME functions make use of flags which are specified using a
|
||||
bitfield which can include one or more of the following values:
|
||||
|
||||
<table>
|
||||
<title>PKCS7 CONSTANTS</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Constant</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>PKCS7_TEXT</entry>
|
||||
<entry>adds text/plain content type headers to encrypted/signed
|
||||
message. If decrypting or verifying, it strips those headers from
|
||||
the output - if the decrypted or verified message is not of MIME type
|
||||
text/plain then an error will occur.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_BINARY</entry>
|
||||
<entry>normally the input message is converted to "canonical" format
|
||||
which is effectlively using CR and LF as end of line: as required by
|
||||
the S/MIME specification. When this options is present, no
|
||||
translation occurs. This is useful when handling binary data which
|
||||
may not be in MIME format.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_NOINTERN</entry>
|
||||
<entry>when verifying a message, certificates (if
|
||||
any) included in the message are normally searched for the
|
||||
signing certificate. With this option only the
|
||||
certificates specified in the <parameter>extracerts</parameter>
|
||||
parameter of <function>openssl_pkcs7_verify</function> are
|
||||
used. The supplied certificates can still be used as
|
||||
untrusted CAs however.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_NOVERIFY</entry>
|
||||
<entry>do not verify the signers certificate of a signed
|
||||
message.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_NOCHAIN</entry>
|
||||
<entry>do not chain verification of signers certificates: that is
|
||||
don't use the certificates in the signed message as untrusted CAs.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_NOCERTS</entry>
|
||||
<entry>when signing a message the signer's certificate is normally
|
||||
included - with this option it is excluded. This will reduce the
|
||||
size of the signed message but the verifier must have a copy of the
|
||||
signers certificate available locally (passed using the
|
||||
<parameter>extracerts</parameter> to
|
||||
<function>openssl_pkcs7_verify</function> for example.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_NOATTR</entry>
|
||||
<entry>normally when a message is signed, a set of attributes are
|
||||
included which include the signing time and the supported symmetric
|
||||
algorithms. With this option they are not included.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_DETACHED</entry>
|
||||
<entry>When signing a message, use cleartext signing with the MIME
|
||||
type multipart/signed. This is the default if the
|
||||
<parameter>flags</parameter> parameter to
|
||||
<function>openssl_pkcs7_sign</function> if you do not specify any
|
||||
flags. If you turn this option off, the message will be signed using
|
||||
opaque signing, which is more resistant to translation by mail relays
|
||||
but cannot be read by mail agents that do not support S/MIME.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>PKCS7_NOSIGS</entry>
|
||||
<entry>Don't try and verify the signatures on a message</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
</para>
|
||||
</sect1>
|
||||
</partintro>
|
||||
|
||||
<refentry id="function.openssl-error-string">
|
||||
<refnamediv>
|
||||
<refname>openssl_error_string</refname>
|
||||
<refpurpose>Return openSSL error message</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>mixed <function>openssl_error_string</function></funcdef>
|
||||
<paramdef>void<parameter></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
Returns an error message string, or false if there are no more error
|
||||
messages to return.
|
||||
</para>
|
||||
<para>
|
||||
<function>openssl_error_string</function> returns the last error from the
|
||||
openSSL library. Error messages are stacked, so this function should be
|
||||
called multiple times to collect all of the information.
|
||||
</para>
|
||||
<para><emphasis>The parameters/return type of this function may change before
|
||||
it appears in a release version of PHP</emphasis></para>
|
||||
<para>
|
||||
<example>
|
||||
<title><function>openssl_error_string</function> example</title>
|
||||
<programlisting role="php">
|
||||
// lets assume you just called an openssl function that failed
|
||||
while($msg = openssl_error_string)
|
||||
echo $msg . "<br>";
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-free-key">
|
||||
<refnamediv>
|
||||
<refname>openssl_free_key</refname>
|
||||
|
|
@ -25,7 +221,7 @@
|
|||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>void <function>openssl_free_key</function></funcdef>
|
||||
<paramdef>int <parameter>key_identifier</parameter></paramdef>
|
||||
<paramdef>resource <parameter>key_identifier</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
|
|
@ -44,13 +240,13 @@
|
|||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>int <function>openssl_get_privatekey</function></funcdef>
|
||||
<paramdef>string <parameter>key</parameter></paramdef>
|
||||
<funcdef>resource <function>openssl_get_privatekey</function></funcdef>
|
||||
<paramdef>mixed <parameter>key</parameter></paramdef>
|
||||
<paramdef>string <parameter><optional>passphrase</optional></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
Returns a positive key identifier on success, or false on error.
|
||||
Returns a positive key resource identifier on success, or false on error.
|
||||
</para>
|
||||
<para>
|
||||
<function>openssl_get_privatekey</function> parses the PEM
|
||||
|
|
@ -71,12 +267,12 @@
|
|||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>int <function>openssl_get_publickey</function></funcdef>
|
||||
<paramdef>string <parameter>certificate</parameter></paramdef>
|
||||
<funcdef>resource <function>openssl_get_publickey</function></funcdef>
|
||||
<paramdef>mixed <parameter>certificate</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
Returns a positive key identifier on success, or false on error.
|
||||
Returns a positive key resource identifier on success, or false on error.
|
||||
</para>
|
||||
<para>
|
||||
<function>openssl_get_publickey</function> extracts the
|
||||
|
|
@ -100,7 +296,7 @@
|
|||
<paramdef>string <parameter>sealed_data</parameter></paramdef>
|
||||
<paramdef>string <parameter>open_data</parameter></paramdef>
|
||||
<paramdef>string <parameter>env_key</parameter></paramdef>
|
||||
<paramdef>int <parameter>priv_key_id</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>priv_key_id</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
|
|
@ -109,9 +305,11 @@
|
|||
</para>
|
||||
<para>
|
||||
<function>openssl_open</function> opens (decrypts)
|
||||
<parameter>sealed_data</parameter> using the private key associtated with
|
||||
<parameter>sealed_data</parameter> using the private key associated with
|
||||
the key identifier <parameter>priv_key_id</parameter> and the envelope key
|
||||
<parameter>env_key</parameter>. The envelope key is generated when the
|
||||
<parameter>env_key</parameter>, and fills
|
||||
<parameter>open_data</parameter> with the decrypted data.
|
||||
The envelope key is generated when the
|
||||
data are sealed and can only be used by one specific private key. See
|
||||
<function>openssl_seal</function> for more information.
|
||||
</para>
|
||||
|
|
@ -224,7 +422,7 @@ openssl_free_key($pk2);
|
|||
<funcdef>bool <function>openssl_sign</function></funcdef>
|
||||
<paramdef>string <parameter>data</parameter></paramdef>
|
||||
<paramdef>string <parameter>signature</parameter></paramdef>
|
||||
<paramdef>int <parameter>priv_key_id</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>priv_key_id</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
|
|
@ -277,7 +475,7 @@ openssl_free_key($pkeyid);
|
|||
<funcdef>int <function>openssl_verify</function></funcdef>
|
||||
<paramdef>string <parameter>data</parameter></paramdef>
|
||||
<paramdef>string <parameter>signature</parameter></paramdef>
|
||||
<paramdef>int <parameter>pub_key_id</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>pub_key_id</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
|
|
@ -291,6 +489,7 @@ openssl_free_key($pkeyid);
|
|||
<parameter>pub_key_id</parameter>. This must be the public key
|
||||
corresponding to the private key used for signing.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><function>openssl_verify</function> example</title>
|
||||
|
|
@ -322,8 +521,420 @@ openssl_free_key($pubkeyid);
|
|||
</simpara>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
</reference>
|
||||
|
||||
<refentry id="function.openssl-pkcs7-decrypt">
|
||||
<refnamediv>
|
||||
<refname>openssl_pkcs7_decrypt</refname>
|
||||
<refpurpose>Decrypts an S/MIME encrypted message</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>bool <function>openssl_pkcs7_decrypt</function></funcdef>
|
||||
<paramdef>string <parameter>infilename</parameter></paramdef>
|
||||
<paramdef>string <parameter>outfilename</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>recipcert</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>recipkey</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
Decrypts the S/MIME encrypted message contained in the file specified by
|
||||
<parameter>infilename</parameter> using the certificate and it's
|
||||
associated private key specified by <parameter>recipcert</parameter> and
|
||||
<parameter>recipkey</parameter>.
|
||||
</para>
|
||||
<para>The decrypted message is output to the
|
||||
file specified by <parameter>outfilename</parameter>
|
||||
</para>
|
||||
<para><emphasis>The parameters/return type of this function may change before
|
||||
it appears in a release version of PHP</emphasis></para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><function>openssl_pkcs7_decrypt</function> example</title>
|
||||
<programlisting role="php">
|
||||
// $cert and $key are assumed to contain your personal certificate and private
|
||||
// key pair, and that you are the recipient of an S/MIME message
|
||||
$infilename = "encrypted.msg"; // this file holds your encrypted message
|
||||
$outfilename = "decrypted.msg"; // make sure you can write to this file
|
||||
|
||||
if (openssl_pkcs7_decrypt($infilename, $outfilename, $cert, $key))
|
||||
echo "decrypted!";
|
||||
else
|
||||
echo "failed to decrypt!";
|
||||
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-pkcs7-encrypt">
|
||||
<refnamediv>
|
||||
<refname>openssl_pkcs7_encrypt</refname>
|
||||
<refpurpose>Encrypt an S/MIME message</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>bool <function>openssl_pkcs7_encrypt</function></funcdef>
|
||||
<paramdef>string <parameter>infilename</parameter></paramdef>
|
||||
<paramdef>string <parameter>outfilename</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>recipcerts</parameter></paramdef>
|
||||
<paramdef>array <parameter>headers</parameter></paramdef>
|
||||
<paramdef>long <parameter><optional>flags</optional></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
<function>openssl_pkcs7_encrypt</function> takes the contents of the
|
||||
file named <parameter>infilename</parameter> and encrypts them using an RC2
|
||||
40-bit cipher so that they can only be read by the intended recipients
|
||||
specified by <parameter>recipcerts</parameter>, which is either a
|
||||
lone X.509 certificate, or an array of X.509 certificates.
|
||||
<parameter>headers</parameter> is an array of headers that
|
||||
will be prepended to the data after it has been encrypted.
|
||||
<parameter>flags</parameter> can be used to specify options that affect
|
||||
the encoding process - see <link linkend="openssl.pkcs7.flags">PKCS7
|
||||
constants</link>.
|
||||
<parameter>headers</parameter> can be either an associative array
|
||||
keyed by header name, or an indexed array, where each element contains
|
||||
a single header line.
|
||||
</para>
|
||||
<para><emphasis>The parameters/return type of this function may change before
|
||||
it appears in a release version of PHP</emphasis></para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><function>openssl_pkcs7_encrypt</function> example</title>
|
||||
<programlisting role="php">
|
||||
// the message you want to encrypt and send to your secret agent
|
||||
// in the field, known as nighthawk. You have his certificate
|
||||
// in the file nighthawk.pem
|
||||
$data = <<<EOD
|
||||
Nighthawk,
|
||||
|
||||
Top secret, for your eyes only!
|
||||
|
||||
The enemy is closing in! Meet me at the cafe at 8.30am
|
||||
to collect your forged passport!
|
||||
|
||||
HQ
|
||||
EOD;
|
||||
// save message to file
|
||||
$fp = fopen("msg.txt", "w");
|
||||
fwrite($fp, $data);
|
||||
fclose($fp);
|
||||
// encrypt it
|
||||
if (openssl_pkcs7_encrypt("msg.txt", "enc.txt", "nighthawk.pem",
|
||||
array("To" => "nighthawk@agent.com", // keyed syntax
|
||||
"From: HQ <hq@cia.com>", // indexed syntax
|
||||
"Subject" => "Eyes only")))
|
||||
{
|
||||
// message encrypted - send it!
|
||||
exec(ini_get("sendmail_path") . " < enc.txt");
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-pkcs7-sign">
|
||||
<refnamediv>
|
||||
<refname>openssl_pkcs7_sign</refname>
|
||||
<refpurpose>sign an S/MIME message</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>bool <function>openssl_pkcs7_sign</function></funcdef>
|
||||
<paramdef>string <parameter>infilename</parameter></paramdef>
|
||||
<paramdef>string <parameter>outfilename</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>signcert</parameter></paramdef>
|
||||
<paramdef>mixed <parameter>privkey</parameter></paramdef>
|
||||
<paramdef>array <parameter>headers</parameter></paramdef>
|
||||
<paramdef>long
|
||||
<parameter><optional>flags</optional></parameter></paramdef>
|
||||
<paramdef>string
|
||||
<parameter><optional>extracertsfilename</optional></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
<function>openssl_pkcs7_sign</function> takes the contents of the file
|
||||
named <parameter>infilename</parameter> and signs them using the
|
||||
certificate and it's matching private key specified by
|
||||
<parameter>signcert</parameter> and <parameter>privkey</parameter>
|
||||
parameters.
|
||||
</para>
|
||||
<para><parameter>headers</parameter> is an array of headers that
|
||||
will be prepended to the data after it has been signed (see
|
||||
<function>openssl_pkcs7_encrypt</function> for more information about
|
||||
the format of this parameter.
|
||||
</para>
|
||||
<para>
|
||||
<parameter>flags</parameter> can be used to alter the output - see <link
|
||||
linkend="openssl.pkcs7.flags">PKCS7 constants</link> - if not specified,
|
||||
it defaults to PKCS7_DETACHED.
|
||||
</para>
|
||||
<para>
|
||||
<parameter>extracerts</parameter> specifies the name of a file containing
|
||||
a bunch of extra certificates to include in the signature which can for
|
||||
example be used to help the recipient to verify the certificate that you used.
|
||||
</para>
|
||||
<para><emphasis>The parameters/return type of this function may change before
|
||||
it appears in a release version of PHP</emphasis></para>
|
||||
|
||||
<para>
|
||||
<example>
|
||||
<title><function>openssl_pkcs7_sign</function> example</title>
|
||||
<programlisting role="php">
|
||||
// the message you want to sign so that recipient can be sure it was you that
|
||||
// sent it
|
||||
$data = <<<EOD
|
||||
|
||||
You have my authorization to spend $10,000 on dinner expenses.
|
||||
|
||||
The CEO
|
||||
HQ
|
||||
EOD;
|
||||
// save message to file
|
||||
$fp = fopen("msg.txt", "w");
|
||||
fwrite($fp, $data);
|
||||
fclose($fp);
|
||||
// encrypt it
|
||||
if (openssl_pkcs7_sign("msg.txt", "signed.txt", "mycert.pem",
|
||||
array("mycert.pem", "mypassphrase"),
|
||||
array("To" => "joes@sales.com", // keyed syntax
|
||||
"From: HQ <ceo@sales.com>", // indexed syntax
|
||||
"Subject" => "Eyes only"))
|
||||
{
|
||||
// message signed - send it!
|
||||
exec(ini_get("sendmail_path") . " < signed.txt");
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-pkcs7-verify">
|
||||
<refnamediv>
|
||||
<refname>openssl_pkcs7_verify</refname>
|
||||
<refpurpose>Verifies the signature of an S/MIME signed message</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>bool <function>openssl_pkcs7_verify</function></funcdef>
|
||||
<paramdef>string <parameter>filename</parameter></paramdef>
|
||||
<paramdef>int <parameter>flags</parameter></paramdef>
|
||||
<paramdef>string <parameter><optional>outfilename</optional></parameter></paramdef>
|
||||
<paramdef>array <parameter><optional>cainfo</optional></parameter></paramdef>
|
||||
<paramdef>string <parameter><optional>extracerts</optional></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
<function>openssl_pkcs7_verify</function> reads the S/MIME message
|
||||
contained in the filename specified by <parameter>filename</parameter> and
|
||||
examines the digital signature. It returns true if the signature is
|
||||
verified, false if it is not correct (the message has been tampered with,
|
||||
or the signing certificate is invalid), or -1 on error.
|
||||
</para>
|
||||
<para>
|
||||
<parameter>flags</parameter> can be used to affect how the signature is
|
||||
verified - see <link linkend="openssl.pkcs7.flags">PKCS7 constants</link>
|
||||
for more information.
|
||||
</para>
|
||||
<para>
|
||||
If the <parameter>outfilename</parameter> is specified, it should be a
|
||||
string holding the name of a file into which the certificates of the
|
||||
persons that signed the messages will be stored in PEM format.
|
||||
</para>
|
||||
<para>
|
||||
If the <parameter>cainfo</parameter> is specified, it should hold
|
||||
information about the trusted CA certificates to use in the verification
|
||||
process - see <link linkend="openssl.cert.verification">certificate
|
||||
verification</link> for more information about this parameter.
|
||||
</para>
|
||||
<para>
|
||||
If the <parameter>extracerts</parameter> is specified, it is the filename
|
||||
of a file containing a bunch of certificates to use as untrusted CAs.
|
||||
</para>
|
||||
<para><emphasis>The parameters/return type of this function may change before
|
||||
it appears in a release version of PHP</emphasis></para>
|
||||
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-x509-checkpurpose">
|
||||
<refnamediv>
|
||||
<refname>openssl_x509_checkpurpose</refname>
|
||||
<refpurpose>Verifies if a certificate can be used for a particular
|
||||
purpose</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>bool <function>openssl_x509_checkpurpose</function></funcdef>
|
||||
<paramdef>mixed <parameter>x509cert</parameter></paramdef>
|
||||
<paramdef>int <parameter>purpose</parameter></paramdef>
|
||||
<paramdef>array <parameter>cainfo</parameter></paramdef>
|
||||
<paramdef>string
|
||||
<parameter><optional>untrustedfile</optional></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
Returns true if the certificate can be used for the intended purpose,
|
||||
false if it cannot, or -1 on error.
|
||||
</para>
|
||||
<para>
|
||||
<function>openssl_x509_checkpurpose</function> examines the certificate
|
||||
specified by <parameter>x509cert</parameter> to see if it can be used for
|
||||
the purpose specified by <parameter>purpose</parameter>.
|
||||
</para>
|
||||
<para>
|
||||
<parameter>cainfo</parameter> should be an array of trusted CA files/dirs
|
||||
as described in <link linkend="openssl.cert.verification">Certificate
|
||||
Verification</link>.
|
||||
</para>
|
||||
<para><parameter>untrustedfile</parameter>, if specified,
|
||||
is the name of a PEM encoded file holding certificates that can be used to
|
||||
help verify the certificate, although no trust in placed in the
|
||||
certificates that come from that file.
|
||||
</para>
|
||||
<para><emphasis>The parameters/return type of this function may change before
|
||||
it appears in a release version of PHP</emphasis></para>
|
||||
<para>
|
||||
<table>
|
||||
<title><function>openssl_x509_checkpurpose</function> purposes</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Constant</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_SSL_CLIENT</entry>
|
||||
<entry>Can the certificate be used for the client side of an SSL
|
||||
connection?</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_SSL_SERVER</entry>
|
||||
<entry>Can the certificate be used for the server side of an SSL
|
||||
connection?</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_NS_SSL_SERVER</entry>
|
||||
<entry>Can the cert be used for Netscape SSL server?</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_SMIME_SIGN</entry>
|
||||
<entry>Can the cert be used to sign S/MIME email?</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_SMIME_ENCRYPT</entry>
|
||||
<entry>Can the cert be used to encrypt S/MIME email?</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_CRL_SIGN</entry>
|
||||
<entry>Can the cert be used to sign a certificate revocation list
|
||||
(CRL)?</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>X509_PURPOSE_ANY</entry>
|
||||
<entry>Can the cert be used for Any/All purposes?</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
These options are not bitfields - you may specify one only!
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-x509-free">
|
||||
<refnamediv>
|
||||
<refname>openssl_x509_free</refname>
|
||||
<refpurpose>Free certificate resource</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>void <function>openssl_x509_free</function></funcdef>
|
||||
<paramdef>resource <parameter>x509cert</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
<function>openssl_x509_free</function> frees the certificate associated
|
||||
with the specified <parameter>x509cert</parameter> resource from memory.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-x509-parse">
|
||||
<refnamediv>
|
||||
<refname>openssl_x509_parse</refname>
|
||||
<refpurpose>Parse an X509 certificate and return the information as an
|
||||
array</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>array <function>openssl_x509_parse</function></funcdef>
|
||||
<paramdef>mixed <parameter>x509cert</parameter></paramdef>
|
||||
<paramdef>bool
|
||||
<parameter><optional>shortnames</optional></parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
<function>openssl_x509_parse</function> returns information about the
|
||||
supplied <parameter>x509cert</parameter>, including fields such as subject
|
||||
name, issuer name, purposes, valid from and valid to dates etc.
|
||||
<parameter>shortnames</parameter> controls how the data is indexed in the
|
||||
array - if <parameter>shortnames</parameter> is true (the default) then
|
||||
fields will be indexed with the short name form, otherwise, the long name
|
||||
form will be used - e.g.: CN is the shortname form of commonName.
|
||||
</para>
|
||||
<para><emphasis>The structure of the returned data is (deliberately) not
|
||||
yet documented, as it is still subject to change.</emphasis></para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
<refentry id="function.openssl-x509-read">
|
||||
<refnamediv>
|
||||
<refname>openssl_x509_read</refname>
|
||||
<refpurpose>Parse an X.509 certificate and return a resource identifier for
|
||||
it</refpurpose>
|
||||
</refnamediv>
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<funcsynopsis>
|
||||
<funcprototype>
|
||||
<funcdef>resource <function>openssl_x509_read</function></funcdef>
|
||||
<paramdef>mixed <parameter>x509certdata</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
<para>
|
||||
<function>openssl_x509_read</function> parses the certificate supplied by
|
||||
<parameter>x509certdata</parameter> and returns a resource identifier for
|
||||
it.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
||||
|
||||
|
||||
|
||||
</reference>
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
mode: sgml
|
||||
|
|
@ -340,3 +951,6 @@ sgml-local-catalogs:nil
|
|||
sgml-local-ecat-files:nil
|
||||
End:
|
||||
-->
|
||||
<!-- Keep this comment for vi/vim/gvim
|
||||
vi: et:ts=1:sw=1:textwidth=78
|
||||
-->
|
||||
|
|
|
|||
Loading…
Reference in a new issue