openssl-csr-new.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: b6d0da041ac2b5eee3820bf2c2062872f4459dfe Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.openssl-csr-new" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>openssl_csr_new</refname>
  <refpurpose>Генерирует <acronym>CSR</acronym></refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>OpenSSLCertificateSigningRequest</type><type>bool</type></type><methodname>openssl_csr_new</methodname>
   <methodparam><type>array</type><parameter>distinguished_names</parameter></methodparam>
   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type class="union"><type>OpenSSLAsymmetricKey</type><type>null</type></type><parameter role="reference">private_key</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>extra_attributes</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Функция <function>openssl_csr_new</function> создаёт новый <acronym>CSR</acronym>
   на основе информации, которую задали в параметре <parameter>distinguished_names</parameter>.
  </para>
  &note.openssl.cnf;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>distinguished_names</parameter></term>
     <listitem>
      <para>
       Уникальное имя (Distinguished Name) или поля субъекта для
       сертификата.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>private_key</parameter></term>
     <listitem>
      <para>
       Для параметра <parameter>private_key</parameter> требуется установить закрытый ключ,
       который сгенерировала функция <function>openssl_pkey_new</function> (или
       который вернула любая другая функция семейства openssl_pkey) или &null;.
       Если значение переменной &null;, то создаётся новый закрытый ключ на основе
       предоставленного параметра <parameter>options</parameter> и присваивается предоставленной переменной.
       Соответствующую открытую часть ключа функция использует, чтобы
       подписать <acronym>CSR</acronym>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       По умолчанию для инициализации запроса используется информация из
       системного файла <literal>openssl.conf</literal>. Можно указать
       секцию конфигурационного файла путём задания ключа
       <literal>config_section_section</literal> в
       параметре <parameter>options</parameter>. Можно также задать альтернативный
       файл конфигурации OpenSSL путём задания ключа
       <literal>config</literal> значением пути до него.
       Соответствие ключей, которые указали в параметре <parameter>options</parameter>,
       ключам из файла <literal>openssl.conf</literal> дают следующие параграфы описания.
       <table>
        <title>Переопределение конфигурации</title>
        <tgroup cols="3">
         <thead>
          <row>
           <entry>Ключ <parameter>options</parameter></entry>
           <entry>Тип</entry>
           <entry>Соответствие в <literal>openssl.conf</literal></entry>
           <entry>Описание</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>digest_alg</entry>
           <entry><type>string</type></entry>
           <entry>default_md</entry>
           <entry>Один из методов <function>openssl_get_md_methods</function></entry>
          </row>
          <row>
           <entry>x509_extensions</entry>
           <entry><type>string</type></entry>
           <entry>x509_extensions</entry>
           <entry>Определяет, какое расширение должно использоваться, чтобы создать
            сертификат x509</entry>
          </row>
          <row>
           <entry>req_extensions</entry>
           <entry><type>string</type></entry>
           <entry>req_extensions</entry>
           <entry>Определяет, какое расширение должно использоваться для создания <acronym>CSR</acronym></entry>
          </row>
          <row>
           <entry>private_key_bits</entry>
           <entry><type>int</type></entry>
           <entry>default_bits</entry>
           <entry>Задаёт, сколько бит должно использоваться для генерации закрытого
            ключа</entry>
          </row>
          <row>
           <entry>private_key_type</entry>
           <entry><type>int</type></entry>
           <entry>none</entry>
           <entry>Задаёт тип создаваемого закрытого ключа. Одна из констант:
            <constant>OPENSSL_KEYTYPE_DSA</constant>,
            <constant>OPENSSL_KEYTYPE_DH</constant>,
            <constant>OPENSSL_KEYTYPE_RSA</constant> или
            <constant>OPENSSL_KEYTYPE_EC</constant>.
            По умолчанию <constant>OPENSSL_KEYTYPE_RSA</constant>.
           </entry>
          </row>
          <row>
           <entry>encrypt_key</entry>
           <entry><type>bool</type></entry>
           <entry>encrypt_key</entry>
           <entry>Должен ли шифроваться (паролем) экспортируемый ключ?</entry>
          </row>
          <row>
           <entry>encrypt_key_cipher</entry>
           <entry><type>int</type></entry>
           <entry>none</entry>
           <entry>
            Одна из <link linkend="openssl.ciphers">констант шифров</link>.
           </entry>
          </row>
          <row>
           <entry>curve_name</entry>
           <entry><type>string</type></entry>
           <entry>none</entry>
           <entry>
            Одно из <function>openssl_get_curve_names</function>.
           </entry>
          </row>
          <row>
           <entry>config</entry>
           <entry><type>string</type></entry>
           <entry>N/A</entry>
           <entry>
            Путь до альтернативного файла конфигурации openssl.conf.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>extra_attributes</parameter></term>
     <listitem>
      <para>
       Параметр <parameter>extra_attributes</parameter> используется для указания дополнительных
       опций для <acronym>CSR</acronym>. И <parameter>distinguished_names</parameter>, и
       <parameter>extra_attributes</parameter> являются ассоциативными массивами, ключи
       которых преобразуются в OI-ы и применяются к соответствующим частям
       запроса.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Функция возвращает <acronym>CSR</acronym> в случае успешного выполнения,
   &true;, в случае успешного создания CSR, но при возникновении ошибки подписания&return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>csr</parameter> теперь принимает экземпляр <classname>OpenSSLCertificateSigningRequest</classname>;
       ранее принимался ресурс (&resource;) типа <literal>OpenSSL X.509 CSR</literal>.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>private_key</parameter> теперь принимает экземпляр <classname>OpenSSLAsymmetricKey</classname>;
       ранее принимался ресурс (&resource;) типа <literal>OpenSSL key</literal>.
      </entry>
     </row>
      <row>
       <entry>7.1.0</entry>
       <entry>
        Параметр <parameter>options</parameter> теперь поддерживает
        <literal>curve_name</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Создание самоподписанного сертификата</title>
    <programlisting role="php">
<![CDATA[
<?php
// для сервера сертификации SSL, commonName является доменным именем
// для сертификатов S/MIME, commonName является владельцем расположения адреса email
// и поля идентификации относятся к владельцу домена или электронной почты,
// подлежащим защите
$dn = array(
    "countryName" => "GB",
    "stateOrProvinceName" => "Somerset",
    "localityName" => "Glastonbury",
    "organizationName" => "The Brain Room Limited",
    "organizationalUnitName" => "PHP Documentation Team",
    "commonName" => "Wez Furlong",
    "emailAddress" => "wez@example.com"
);

// Создание пары закрытый/открытый ключ
$privkey = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));

// Создание CSR
$csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

// Создание самоподписанного сертификата со сроком жизни 365 дней
$x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

// Сохранение закрытого ключа, CSR и самоподписанного сертификата
openssl_csr_export($csr, $csrout) and var_dump($csrout);
openssl_x509_export($x509, $certout) and var_dump($certout);
openssl_pkey_export($privkey, $pkeyout, "mypassword") and var_dump($pkeyout);

// Покажем возникшие ошибки, если они были
while (($e = openssl_error_string()) !== false) {
    echo $e . "\n";
}
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Создание самоподписанного ECC сертификата (начиная с PHP 7.1.0)</title>
    <programlisting role="php">
<![CDATA[
<?php
$subject = array(
    "commonName" => "docs.php.net",
);

// Создание пары закрытый/открытый ключ
$private_key = openssl_pkey_new(array(
    "private_key_type" => OPENSSL_KEYTYPE_EC,
    "curve_name" => 'prime256v1',
));

// Создание CSR
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

// Создание самоподписанного EC сертификата
$x509 = openssl_csr_sign($csr, null, $private_key, $days=365, array('digest_alg' => 'sha384'));
openssl_x509_export_to_file($x509, 'ecc-cert.pem');
openssl_pkey_export_to_file($private_key, 'ecc-private.key');
?>
]]>
    </programlisting>
   </example>


  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>openssl_csr_sign</function></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->