openssl-csr-new.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: f0d11929d41082d71dcf8338a18e04412c656fa0 Maintainer: jaenecke Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.openssl-csr-new" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>openssl_csr_new</refname>
  <refpurpose>Erzeugt einen <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> erzeugt einen neuen
   <acronym>CSR</acronym> (Certificate Signing Request,
   Zertifikats-Signierungsanfrage) basierend auf den Informationen, die mit
   dem Parameter <parameter>distinguished_names</parameter> angegeben werden.
  </para>
  &note.openssl.cnf;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>distinguished_names</parameter></term>
     <listitem>
      <para>
       Der Distinguished Name oder die Subjekt-Felder, die in das Zertifikat
       aufgenommen werden sollen. <parameter>distinguished_names</parameter>
       ist ein assoziatives Array, in dem die Schlüssel die Attributnamen der
       Distinguished Names darstellen und die Werte entweder Zeichenketten (für
       einen einzelnen Wert) oder Arrays (wenn mehrere Werte festgelegt werden
       müssen) sein können.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>private_key</parameter></term>
     <listitem>
      <para>
       <parameter>private_key</parameter> muss auf einen zuvor mit
       <function>openssl_pkey_new</function> erzeugten (oder anderweitig von
       der openssl_pkey-Familie erhaltenen) privaten Schlüssel oder auf eine
       &null;-Variable gesetzt werden. Wenn der Wert &null; ist, wird ein neuer
       privater Schlüssel basierend auf den übergebenen
       <parameter>options</parameter> erzeugt und der übergebenen Variablen
       zugewiesen. Der zugehörige öffentliche Teil des Schlüssels wird zum
       Signieren des <acronym>CSR</acronym> verwendet.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       In der Standardeinstellung werden die Informationen für die Anfrage aus
       der <literal>openssl.conf</literal> des Systems verwendet; ein Abschnitt
       der Konfigurationsdatei kann durch Setzen des Schlüssels
       <literal>config_section</literal> in <parameter>options</parameter>
       angegeben werden. Außerdem kann eine alternative
       OpenSSL-Konfigurationsdatei angegeben, indem der Wert des Schlüssels
       <literal>config</literal> auf den Pfad der zu verwendenden Datei gesetzt
       wird. Die unten in der Tabelle aufgeführten Schlüssel, soweit in
       <parameter>options</parameter> vorhanden, verhalten sich genau gleich
       wie die entsprechenden Werte in der <literal>openssl.conf</literal>.
       <table>
        <title>Überschreiben der Konfiguration</title>
        <tgroup cols="3">
         <thead>
          <row>
           <entry><parameter>options</parameter>-Schlüssel</entry>
           <entry>Typ</entry>
           <entry><literal>openssl.conf</literal>-Entsprechung</entry>
           <entry>Beschreibung</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry>digest_alg</entry>
           <entry><type>string</type></entry>
           <entry>default_md</entry>
           <entry>
            Digest-Methode oder Signaturhash, üblicherweise eins von
            <function>openssl_get_md_methods</function>.
           </entry>
          </row>
          <row>
           <entry>x509_extensions</entry>
           <entry><type>string</type></entry>
           <entry>x509_extensions</entry>
           <entry>
            Bestimmt, welche Erweiterung verwendet werden soll, wenn ein
            x509-Zertifikat erzeugt werden soll.
           </entry>
          </row>
          <row>
           <entry>req_extensions</entry>
           <entry><type>string</type></entry>
           <entry>req_extensions</entry>
           <entry>
            Bestimmt welche Erweiterung verwendet werden soll, wenn eine
            Zertifikats-Signierungsanfrage (<acronym>CSR</acronym>) erzeugt
            werden soll.
           </entry>
          </row>
          <row>
           <entry>private_key_bits</entry>
           <entry><type>int</type></entry>
           <entry>default_bits</entry>
           <entry>
            Bestimmt wieviele Bits verwendet werden sollen, um einen privaten
            Schlüssel zu erzeugen.
           </entry>
          </row>
          <row>
           <entry>private_key_type</entry>
           <entry><type>int</type></entry>
           <entry>keine</entry>
           <entry>
            Bestimmt den Typ des privaten Schlüssels, der erzeugt werden soll.
            Der Typ kann einer der folgenden sein:
            <constant>OPENSSL_KEYTYPE_DSA</constant>,
            <constant>OPENSSL_KEYTYPE_DH</constant>,
            <constant>OPENSSL_KEYTYPE_RSA</constant> oder
            <constant>OPENSSL_KEYTYPE_EC</constant>. Der Standardwert ist
            <constant>OPENSSL_KEYTYPE_RSA</constant>.
           </entry>
          </row>
          <row>
           <entry>encrypt_key</entry>
           <entry><type>bool</type></entry>
           <entry>encrypt_key</entry>
           <entry>
            Soll ein exportierter Schlüssel (mit Passphrase) verschlüsselt
            werden?
           </entry>
          </row>
          <row>
           <entry>encrypt_key_cipher</entry>
           <entry><type>int</type></entry>
           <entry>keine</entry>
           <entry>
            Eine der <link linkend="openssl.ciphers">Ziffer-Konstanten</link>.
           </entry>
          </row>
          <row>
           <entry>curve_name</entry>
           <entry><type>string</type></entry>
           <entry>none</entry>
           <entry>
            Einer der <function>openssl_get_curve_names</function>.
           </entry>
          </row>
          <row>
           <entry>config</entry>
           <entry><type>string</type></entry>
           <entry>N/A</entry>
           <entry>
            Pfad zur eigenen alternativen openssl.conf-Datei.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>extra_attributes</parameter></term>
     <listitem>
      <para>
       <parameter>extra_attributes</parameter> wird verwendet, um zusätzliche
       Attribute für den <acronym>CSR</acronym> anzugeben. Es handelt sich um
       ein assoziatives Array, dessen Schlüssel in OIDs umgewandelt und als
       <acronym>CSR</acronym>-Attribute verwendet werden.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt bei Erfolg den <acronym>CSR</acronym> zurück; &true; wenn die
   <acronym>CSR</acronym>-Erstellung erfolgreich war, aber das Signieren
   fehlgeschlagen ist. &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.4.0</entry>
      <entry>
       Das assoziative Array <parameter>distinguished_names</parameter>
       unterstützt nun Arrays als Werte, sodass mehrere Werte für ein einzelnes
       Attribut angegeben werden können.
      </entry>
     </row>
     <row>
      <entry>8.4.0</entry>
      <entry>
       Der Parameter <parameter>extra_attributes</parameter> setzt nun korrekt
       die CSR-Attribute, anstatt wie bisher fälschlicherweise den
       Distinguished Name des Subjekts zu ändern.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       Bei Erfolg gibt diese Funktion nun eine
       <classname>OpenSSLCertificateSigningRequest</classname>-Instanz zurück;
       vorher wurde eine &resource; vom Typ <literal>OpenSSL X.509
       CSR</literal> zurückgegeben.
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>private_key</parameter> akzeptiert nun eine
       <classname>OpenSSLAsymmetricKey</classname>-Instanz; vorher wurde eine
       &resource; vom Typ <literal>OpenSSL-Schlüssel</literal> akzeptiert.
      </entry>
     </row>
     <row>
      <entry>7.1.0</entry>
      <entry>
       <parameter>options</parameter> unterstützt nun auch
       <literal>curve_name</literal>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Erzeugen eines selbstsignierten Zertifikats</title>
    <programlisting role="php">
<![CDATA[
<?php
// bei SSL-Zertifikate ist der commonName der zu sichernde Domain-Name
// bei S/MIME-Zertifikate ist der commonName der Eigentümer der E-Mail-Adresse
// die Felder location und identification beziehen sich auf den Eigentümer der
// zu sichernden Domain oder des E-Mail-Eigentümers
$dn = array(
    "countryName" => "GB",
    "stateOrProvinceName" => "Somerset",
    "localityName" => "Glastonbury",
    "organizationName" => "The Brain Room Limited",
    "organizationalUnitName" => "PHP Documentation Team",
    "commonName" => "Wez Furlong",
    "emailAddress" => "wez@example.com"
);

// Erzeugen eines neuen privaten (und öffentlichen) Schlüsselpaars
$privkey = openssl_pkey_new(array(
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
));

// Erzeugen einer Zertifikats-Signierungsanfrage
$csr = openssl_csr_new($dn, $privkey, array('digest_alg' => 'sha256'));

// Erzeugen eines selbstsignierten Zertifikats, das für die Dauer von 365 Tagen
// gültig ist.
$x509 = openssl_csr_sign($csr, null, $privkey, $days=365, array('digest_alg' => 'sha256'));

// Sichern des privaten Schlüssels, des CSR und des selbstsignierten
// Zertifikats für die spätere Verwendung
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);

// Anzeigen aller aufgetretenen Fehler
while (($e = openssl_error_string()) !== false) {
    echo $e . "\n";
}
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Erzeugen eines selbstsignierten ECC-Zertifikats (von PHP 7.1.0 an)</title>
    <programlisting role="php">
<![CDATA[
<?php
$subject = array(
    "commonName" => "docs.php.net",
);

// Erzeugen eines neuen privaten (und öffentlichen) Schlüsselpaars
$private_key = openssl_pkey_new(array(
    "private_key_type" => OPENSSL_KEYTYPE_EC,
    "curve_name" => 'prime256v1',
));

// Erzeugen einer Zertifikats-Signierungsanfrage
$csr = openssl_csr_new($subject, $private_key, array('digest_alg' => 'sha384'));

// Erzeugen eines selbstsignierten EC-Zertifikats
$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
-->