php-doc-en/reference/openssl/functions/openssl-csr-new.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<!-- splitted from ./en/functions/openssl.xml, last change in rev 1.19 -->
  <refentry id="function.openssl-csr-new">
   <refnamediv>
    <refname>openssl_csr_new</refname>
    <refpurpose>Generates a 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>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>
    <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>
    <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>
    &reference.openssl.note-openssl-cnf;
    <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>string</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>
    <simpara>
     &return.success;
    </simpara>
    <para>
     <example>
      <title><function>openssl_csr_new</function> example - 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 debug_zval_dump($csrout);
openssl_x509_export($sscert, $certout) and debug_zval_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and debug_zval_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
-->