<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.openssl-csr-new">
 <refnamediv>
  <refname>openssl_csr_new</refname>
  <refpurpose>Generates a CSR</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>openssl_csr_new</methodname>
   <methodparam><type>array</type><parameter>dn</parameter></methodparam>
   <methodparam><type>resource</type><parameter role="reference">privkey</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>configargs</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>extraattribs</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>openssl_csr_new</function> generates a new CSR (Certificate Signing Request)
   based on the information provided by <parameter>dn</parameter>, which represents the
   Distinguished Name to be used in the certificate.
  </para>
  &note.openssl.cnf;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dn</parameter></term>
     <listitem>
      <para>
       The Distinguished Name to be used in the certificate.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>privkey</parameter></term>
     <listitem>
      <para>
       <parameter>privkey</parameter> should be set to a private key that was
       previously generated by <function>openssl_pkey_new</function> (or
       otherwise obtained from the other openssl_pkey family of functions).
       The corresponding public portion of the key will be used to sign the
       CSR.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>configargs</parameter></term>
     <listitem>
      <para>
       By default, the information in your system <literal>openssl.conf</literal>
       is used to initialize the request; you can specify a configuration file
       section by setting the <literal>config_section_section</literal> key of
       <parameter>configargs</parameter>.  You can also specify an alternative
       openssl configuration file by setting the value of the
       <literal>config</literal> key to the path of the file you want to use.
       The following keys, if present in <parameter>configargs</parameter>
       behave as their equivalents in the <literal>openssl.conf</literal>, as
       listed in the table below.
       <table>
        <title>Configuration overrides</title>
        <tgroup cols="3">
         <thead>
          <row>
           <entry><parameter>configargs</parameter> key</entry>
           <entry>type</entry>
           <entry><literal>openssl.conf</literal> equivalent</entry>
           <entry>description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>digest_alg</entry>
           <entry><type>string</type></entry>
           <entry>default_md</entry>
           <entry>Selects which digest method to use</entry>
          </row>
          <row>
           <entry>x509_extensions</entry>
           <entry><type>string</type></entry>
           <entry>x509_extensions</entry>
           <entry>Selects which extensions should be used when creating an x509
           certificate</entry>
          </row>
          <row>
           <entry>req_extensions</entry>
           <entry><type>string</type></entry>
           <entry>req_extensions</entry>
           <entry>Selects which extensions should be used when creating a CSR</entry>
          </row>
          <row>
           <entry>private_key_bits</entry>
           <entry><type>integer</type></entry>
           <entry>default_bits</entry>
           <entry>Specifies how many bits should be used to generate a private
            key</entry>
          </row>
          <row>
           <entry>private_key_type</entry>
           <entry><type>integer</type></entry>
           <entry>none</entry>
           <entry>Specifies the type of private key to create.  This can be one
            of <constant>OPENSSL_KEYTYPE_DSA</constant>,
            <constant>OPENSSL_KEYTYPE_DH</constant> or
            <constant>OPENSSL_KEYTYPE_RSA</constant>.
            The default value is <constant>OPENSSL_KEYTYPE_RSA</constant> which
            is currently the only supported key type.
           </entry>
          </row>
          <row>
           <entry>encrypt_key</entry>
           <entry><type>boolean</type></entry>
           <entry>encrypt_key</entry>
           <entry>Should an exported key (with passphrase) be encrypted?</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>extraattribs</parameter></term>
     <listitem>
      <para>
       <parameter>extraattribs</parameter> is used to specify additional
       configuration options for the CSR.  Both <parameter>dn</parameter> and
       <parameter>extraattribs</parameter> are associative arrays whose keys are
       converted to OIDs and applied to the relevant part of the request.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the CSR.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Creating a self-signed-certificate</title>
    <programlisting role="php">
<![CDATA[
<?php
// Fill in data for the distinguished name to be used in the cert
// You must change the values of these keys to match your name and
// company, or more precisely, the name and company of the person/site
// that you are generating the certificate for.
// For SSL certificates, the commonName is usually the domain name of
// that will be using the certificate, but for S/MIME certificates,
// the commonName will be the name of the individual who will use the
// certificate.
$dn = array(
    "countryName" => "UK",
    "stateOrProvinceName" => "Somerset",
    "localityName" => "Glastonbury",
    "organizationName" => "The Brain Room Limited",
    "organizationalUnitName" => "PHP Documentation Team",
    "commonName" => "Wez Furlong",
    "emailAddress" => "wez@example.com"
);

// Generate a new private (and public) key pair
$privkey = openssl_pkey_new();

// Generate a certificate signing request
$csr = openssl_csr_new($dn, $privkey);

// You will usually want to create a self-signed certificate at this
// point until your CA fulfills your request.
// This creates a self-signed cert that is valid for 365 days
$sscert = openssl_csr_sign($csr, null, $privkey, 365);

// Now you will want to preserve your private key, CSR and self-signed
// cert so that they can be installed into your web server, mail server
// or mail client (depending on the intended use of the certificate).
// This example shows how to get those things into variables, but you
// can also store them directly into files.
// Typically, you will send the CSR on to your CA who will then issue
// you with the "real" certificate.
openssl_csr_export($csr, $csrout) and var_dump($csrout);
openssl_x509_export($sscert, $certout) and var_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

// Show any errors that occurred here
while (($e = openssl_error_string()) !== false) {
    echo $e . "\n";
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

</refentry>

<!-- 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
-->