<!-- D O   N O T   E D I T   T H I S   F I L E   ! ! !  

     it is still here for historical reasons only 
     (as translators may need to check old revision diffs)

     if you want to change things documented in this file
     you should now edit the files found under en/reference
     instead -->
     
     <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.23 $ -->
 <reference id="ref.openssl">
  <title>OpenSSL functions</title>
  <titleabbrev>OpenSSL</titleabbrev>
  <partintro>
	   &warn.experimental;
  <sect1 id="openssl.intro">
  <title>Introduction</title>
  <para>
   This module uses the functions of <ulink
   url="&url.openssl;">OpenSSL</ulink> for generation and verification
   of signatures and for sealing (encrypting) and opening (decrypting)
   data. PHP-4.0.4pl1 requires OpenSSL &gt;= 0.9.6, but PHP-4.0.5 and greater
   with also work with OpenSSL &gt;= 0.9.5.
  </para>
   <note>
   <para>Please keep in mind that this extension is still considered
   experimental!</para>
  </note>
  <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/Certificate 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 effectively 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>
   <note>
     <para>These constants were added in 4.0.6.</para>
    </note>


  </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>
     <methodsynopsis>
      <type>mixed</type><methodname>openssl_error_string</methodname>
      <void/>
     </methodsynopsis>
	&warn.experimental.func;
    <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">
<![CDATA[
// lets assume you just called an openssl function that failed
while($msg = openssl_error_string())
    echo $msg . "<br />\n";
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      This function was added in 4.0.6. 
     </para>
    </note>
   </refsect1>
  </refentry>
  
  <refentry id="function.openssl-free-key">
   <refnamediv>
    <refname>openssl_free_key</refname>
    <refpurpose>Free key resource</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>openssl_free_key</methodname>
      <methodparam><type>resource</type><parameter>key_identifier</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     <function>openssl_free_key</function> frees the key associated with
     the specified <parameter>key_identifier</parameter> from memory.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-get-privatekey">
   <refnamediv>
    <refname>openssl_get_privatekey</refname>
    <refpurpose>Prepare a PEM formatted private key for use</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>openssl_get_privatekey</methodname>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     Returns a positive key resource identifier on success, or &false; on error.
    </para>
    <para>
     <function>openssl_get_privatekey</function> parses the PEM
     formatted private key specified by <parameter>key</parameter>
     and prepares it for use by other functions.
     The optional parameter <parameter>passphrase</parameter> must be used if
     the specified key is encrypted (protected by a passphrase).
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-get-publickey">
   <refnamediv>
    <refname>openssl_get_publickey</refname> 
    <refpurpose>Extract public key from certificate and prepare it for use</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>openssl_get_publickey</methodname>
      <methodparam><type>mixed</type><parameter>certificate</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     Returns a positive key resource identifier on success, or &false; on error.
    </para>
    <para>
     <function>openssl_get_publickey</function> extracts the
     public key from an X.509 certificate specified by
     <parameter>certificate</parameter> and prepares it for use by other
     functions.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-open">
   <refnamediv>
    <refname>openssl_open</refname>
    <refpurpose>Open sealed data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_open</methodname>
      <methodparam><type>string</type><parameter>sealed_data</parameter></methodparam>
      <methodparam><type>string</type><parameter>open_data</parameter></methodparam>
      <methodparam><type>string</type><parameter>env_key</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>priv_key_id</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     &return.success; If successful the opened
     data is returned in <parameter>open_data</parameter>.
    </para>
    <para>
     <function>openssl_open</function> opens (decrypts)
     <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>, 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>
    <para>
     <example>
      <title><function>openssl_open</function> example</title>
      <programlisting role="php">
<![CDATA[
// $sealed and $env_key are assumed to contain the sealed data
// and our envelope key, both given to us by the sealer.

// fetch private key from file and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);

// decrypt the data and store it in $open
if (openssl_open($sealed, $open, $env_key, $pkeyid))
    echo "here is the opened data: ", $open;
else
    echo "failed to open data";

// free the private key from memory
openssl_free_key($pkeyid);
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     See also <function>openssl_seal</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-seal">
   <refnamediv>
    <refname>openssl_seal</refname>
    <refpurpose>Seal (encrypt) data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>openssl_seal</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>sealed_data</parameter></methodparam>
      <methodparam><type>array</type><parameter>env_keys</parameter></methodparam>
      <methodparam><type>array</type><parameter>pub_key_ids</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     Returns the length of the sealed data on success, or &false; on error.
     If successful the sealed data is returned in
     <parameter>sealed_data</parameter>, and the envelope keys in
     <parameter>env_keys</parameter>.

    </para>
    <para>
     <function>openssl_seal</function> seals (encrypts)
     <parameter>data</parameter> by using RC4 with a randomly generated
     secret key. The key is encrypted with each of the public keys
     associated with the identifiers in <parameter>pub_key_ids</parameter>
     and each encrypted key is returned
     in <parameter>env_keys</parameter>. This means that one can send
     sealed data to multiple recipients (provided one has obtained their
     public keys). Each recipient must receive both the sealed data and
     the envelope key that was encrypted with the recipient's public key.
    </para>
    <para>
     <example>
      <title><function>openssl_seal</function> example</title>
      <programlisting role="php">
<![CDATA[
// $data is assumed to contain the data to be sealed

// fetch public keys for our recipients, and ready them
$fp = fopen("/src/openssl-0.9.6/demos/maurice/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk1 = openssl_get_publickey($cert);
// Repeat for second recipient
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pk2 = openssl_get_publickey($cert);

// seal message, only owners of $pk1 and $pk2 can decrypt $sealed with keys
// $ekeys[0] and $ekeys[1] respectively.
openssl_seal($data, $sealed, $ekeys, array($pk1,$pk2));

// free the keys from memory
openssl_free_key($pk1);
openssl_free_key($pk2);
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     See also <function>openssl_open</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-sign">
   <refnamediv>
    <refname>openssl_sign</refname>
    <refpurpose>Generate signature</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_sign</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>signature</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>priv_key_id</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     &return.success;
     If successful the signature is returned in
     <parameter>signature</parameter>. 
    </para>
    <para>
     <function>openssl_sign</function> computes a signature for the
     specified <parameter>data</parameter> by using SHA1 for hashing
     followed by encryption using the private key associated with
     <parameter>priv_key_id</parameter>. Note that the data itself is
     not encrypted.
    </para>
    <para>
     <example>
      <title><function>openssl_sign</function> example</title>
      <programlisting role="php">
<![CDATA[
// $data is assumed to contain the data to be signed

// fetch private key from file and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/key.pem", "r");
$priv_key = fread($fp, 8192);
fclose($fp);
$pkeyid = openssl_get_privatekey($priv_key);

// compute signature
openssl_sign($data, $signature, $pkeyid);

// free the key from memory
openssl_free_key($pkeyid);
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     See also <function>openssl_verify</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-verify">
   <refnamediv>
    <refname>openssl_verify</refname>
    <refpurpose>Verify signature</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>openssl_verify</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>signature</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>pub_key_id</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <para>
     Returns 1 if the signature is correct, 0 if it is incorrect, and
     -1 on error.
    </para>
    <para>
     <function>openssl_verify</function> verifies that the
     <parameter>signature</parameter> is correct for the specified
     <parameter>data</parameter> using the public key associated with
     <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>
      <programlisting role="php">
<![CDATA[
// $data and $signature are assumed to contain the data and the signature

// fetch public key from certificate and ready it
$fp = fopen("/src/openssl-0.9.6/demos/sign/cert.pem", "r");
$cert = fread($fp, 8192);
fclose($fp);
$pubkeyid = openssl_get_publickey($cert);

// state whether signature is okay or not
$ok = openssl_verify($data, $signature, $pubkeyid);
if ($ok == 1)
    echo "good";
elseif ($ok == 0)
    echo "bad";
else
    echo "ugly, error checking signature";

// free the key from memory
openssl_free_key($pubkeyid);
]]>
      </programlisting>
     </example>
    </para>
    <simpara>
     See also <function>openssl_sign</function>.
    </simpara>
   </refsect1>
  </refentry>

  <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>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_pkcs7_decrypt</methodname>
      <methodparam><type>string</type><parameter>infilename</parameter></methodparam>
      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>recipcert</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>recipkey</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <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>
     <example>
      <title><function>openssl_pkcs7_decrypt</function> example</title>
      <programlisting role="php">
<![CDATA[
// $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>
    <note>
     <para>This function was added in 4.0.6.</para>
    </note>

   </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>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_pkcs7_encrypt</methodname>
      <methodparam><type>string</type><parameter>infilename</parameter></methodparam>
      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>recipcerts</parameter></methodparam>
      <methodparam><type>array</type><parameter>headers</parameter></methodparam>
      <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
	&warn.experimental.func;
    <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>
     <example>
      <title><function>openssl_pkcs7_encrypt</function> example</title>
      <programlisting role="php">
<![CDATA[
// 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>
  <note>
     <para>This function was added in 4.0.6.</para>
    </note>


   </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>
    <methodsynopsis>
     <type>bool</type><methodname>openssl_pkcs7_sign</methodname>
     <methodparam><type>string</type><parameter>infilename</parameter></methodparam>
     <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
     <methodparam><type>mixed</type><parameter>signcert</parameter></methodparam>
     <methodparam><type>mixed</type><parameter>privkey</parameter></methodparam>
     <methodparam><type>array</type><parameter>headers</parameter></methodparam>
     <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>extracertsfilename</parameter></methodparam>
    </methodsynopsis>
	&warn.experimental.func;
   <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>
     <example>
      <title><function>openssl_pkcs7_sign</function> example</title>
      <programlisting role="php">
<![CDATA[
// 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
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>
  <note>
     <para>This function was added in 4.0.6.</para>
    </note>


  </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>
    <methodsynopsis>
     <type>bool</type><methodname>openssl_pkcs7_verify</methodname>
     <methodparam><type>string</type><parameter>filename</parameter></methodparam>
     <methodparam><type>int</type><parameter>flags</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>outfilename</parameter></methodparam>
     <methodparam choice="opt"><type>array</type><parameter>cainfo</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>extracerts</parameter></methodparam>
    </methodsynopsis>
	&warn.experimental.func;
   <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>
  <note>
     <para>This function was added in 4.0.6.</para>
    </note>


  </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>
    <methodsynopsis>
     <type>bool</type><methodname>openssl_x509_checkpurpose</methodname>
     <methodparam><type>mixed</type><parameter>x509cert</parameter></methodparam>
     <methodparam><type>int</type><parameter>purpose</parameter></methodparam>
     <methodparam><type>array</type><parameter>cainfo</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>untrustedfile</parameter></methodparam>
    </methodsynopsis>
	&warn.experimental.func;
   <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>
    <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>
   <note>
     <para>This function was added in 4.0.6.</para>
    </note>


  </refsect1>
 </refentry>

 <refentry id="function.openssl-x509-free">
  <refnamediv>
   <refname>openssl_x509_free</refname>
   <refpurpose>Free certificate resource</refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
    <methodsynopsis>
     <type>void</type><methodname>openssl_x509_free</methodname>
     <methodparam><type>resource</type><parameter>x509cert</parameter></methodparam>
    </methodsynopsis>
	&warn.experimental.func;
   <para>
    <function>openssl_x509_free</function> frees the certificate associated
    with the specified <parameter>x509cert</parameter> resource from memory.
   </para>
  <note>
     <para>This function was added in 4.0.6.</para>
    </note>


  </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>
    <methodsynopsis>
     <type>array</type><methodname>openssl_x509_parse</methodname>
     <methodparam><type>mixed</type><parameter>x509cert</parameter></methodparam>
     <methodparam choice="opt"><type>bool</type><parameter>shortnames</parameter></methodparam>
    </methodsynopsis>
	&warn.experimental.func;
   <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>
   <note>
     <para>This function was added in 4.0.6.</para>
    </note>


  </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>
    <methodsynopsis>
     <type>resource</type><methodname>openssl_x509_read</methodname>
     <methodparam><type>mixed</type><parameter>x509certdata</parameter></methodparam>
    </methodsynopsis>
	&warn.experimental.func;
   <para>
    <function>openssl_x509_read</function> parses the certificate supplied by
    <parameter>x509certdata</parameter> and returns a resource identifier for
    it.
   </para>
  <note>
     <para>This function was added in 4.0.6.</para>
    </note>


  </refsect1>
 </refentry>
 


  <refentry id="function.openssl-x509-export-to-file">
   <refnamediv>
    <refname>openssl_x509_export_to_file</refname>
    <refpurpose>Exports a CERT to file or a var </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_x509_export_to_file</methodname>
      <methodparam><type>mixed</type><parameter>x509</parameter></methodparam>
      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-x509-export">
   <refnamediv>
    <refname>openssl_x509_export</refname>
    <refpurpose>Exports a CERT to file or a var </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_x509_export</methodname>
      <methodparam><type>mixed</type><parameter>x509</parameter></methodparam>
      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-x509-check-private-key">
   <refnamediv>
    <refname>openssl_x509_check_private_key</refname>
    <refpurpose>Checks if a private key corresponds to a CERT </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_x509_check_private_key</methodname>
      <methodparam><type>mixed</type><parameter>cert</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-csr-export-to-file">
   <refnamediv>
    <refname>openssl_csr_export_to_file</refname>
    <refpurpose>Exports a CSR to file or a var </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_csr_export_to_file</methodname>
      <methodparam><type>resource</type><parameter>csr</parameter></methodparam>
      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-csr-export">
   <refnamediv>
    <refname>openssl_csr_export</refname>
    <refpurpose>Exports a CSR to file or a var </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_csr_export</methodname>
      <methodparam><type>resource</type><parameter>csr</parameter></methodparam>
      <methodparam><type>string</type><parameter>out</parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>notext</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-csr-sign">
   <refnamediv>
    <refname>openssl_csr_sign</refname>
    <refpurpose>Signs a cert with another CERT </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>openssl_csr_sign</methodname>
      <methodparam><type>mixed</type><parameter>csr</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>x509</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>priv_key</parameter></methodparam>
      <methodparam><type>long</type><parameter>days</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-csr-new">
   <refnamediv>
    <refname>openssl_csr_new</refname>
    <refpurpose>Generates a privkey and CSR </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_csr_new</methodname>
      <methodparam><type>array</type><parameter>dn</parameter></methodparam>
      <methodparam><type>resource</type><parameter>privkey</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>extraattribs</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-pkey-new">
   <refnamediv>
    <refname>openssl_pkey_new</refname>
    <refpurpose>Generates a new private key </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>openssl_pkey_new</methodname>
      <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-pkey-export-to-file">
   <refnamediv>
    <refname>openssl_pkey_export_to_file</refname>
    <refpurpose>Gets an exportable representation of a key into a file </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_pkey_export_to_file</methodname>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      <methodparam><type>string</type><parameter>outfilename</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>config_args</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-pkey-export">
   <refnamediv>
    <refname>openssl_pkey_export</refname>
    <refpurpose>Gets an exportable representation of a key into a string or file </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_pkey_export</methodname>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>out</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>passphrase</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>config_args</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-private-encrypt">
   <refnamediv>
    <refname>openssl_private_encrypt</refname>
    <refpurpose>Encrypts data with private key </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_private_encrypt</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>crypted</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>padding</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-private-decrypt">
   <refnamediv>
    <refname>openssl_private_decrypt</refname>
    <refpurpose>Decrypts data with private key </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_private_decrypt</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>crypted</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>padding</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-public-encrypt">
   <refnamediv>
    <refname>openssl_public_encrypt</refname>
    <refpurpose>Encrypts data with public key </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_public_encrypt</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>crypted</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>padding</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.openssl-public-decrypt">
   <refnamediv>
    <refname>openssl_public_decrypt</refname>
    <refpurpose>Decrypts data with public key </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>openssl_public_decrypt</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam><type>string</type><parameter>crypted</parameter></methodparam>
      <methodparam><type>resource</type><parameter>key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>padding</parameter></methodparam>
     </methodsynopsis>
     &warn.experimental.func;
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

 
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->