initial translation in openssl/functions

reference/openssl/functions/openssl-random-pseudo-bytes.xml

@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 52c495140bdb84f45f186bfb1cccf09788b0121e Maintainer: leonardolara Status: ready -->
+<refentry xml:id="function.openssl-random-pseudo-bytes" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>openssl_random_pseudo_bytes</refname>
+  <refpurpose>Gera uma sequência pseudo-aleatória de bytes</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>string</type><methodname>openssl_random_pseudo_bytes</methodname>
+   <methodparam><type>int</type><parameter>length</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter role="reference">strong_result</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+   Gera uma <type>string</type> de bytes pseudo-aleatórios, com o número de bytes
+   determinado pelo parâmetro <parameter>length</parameter>.
+  </para>
+  <para>
+   Também indica se um algoritmo criptograficamente forte foi usado para produzir os
+   bytes pseudo-aleatórios, e faz isso através do parâmetro opcional <parameter>strong_result</parameter>.
+   É raro que isso seja &false;, mas alguns sistemas podem estar quebrados ou antigos.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>length</parameter></term>
+     <listitem>
+      <para>
+       O comprimento da sequência de bytes desejada. Deve ser um número inteiro positivo menor ou igual a <literal>2147483647</literal>.
+       O PHP tentará converter este parâmetro em um número inteiro não nulo para usá-lo.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>strong_result</parameter></term>
+     <listitem>
+      <para>
+       Se passado para a função, conterá um valor <type>bool</type> que determina
+       se o algoritmo usado era "criptograficamente forte", por exemplo, seguro para uso com GPG,
+       senhas, etc. &true; se sim, caso contrário &false;.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Retorna a &string; de bytes gerada.
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   <function>openssl_random_pseudo_bytes</function> lança uma <classname>Exception</classname>
+   em caso de falha.
+  </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>strong_result</parameter> agora pode ser nulo.
+      </entry>
+     </row>
+     <row>
+      <entry>7.4.0</entry>
+      <entry>
+       A função não retorna mais &false; em caso de falha, mas em vez disso lança uma <classname>Exception</classname>.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Exemplo de <function>openssl_random_pseudo_bytes</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+for ($i = 1; $i <= 4; $i++) {
+    $bytes = openssl_random_pseudo_bytes($i, $cstrong);
+    $hex   = bin2hex($bytes);
+
+    echo "Comprimentos: Bytes: $i e Hex: " . strlen($hex) . PHP_EOL;
+    var_dump($hex);
+    var_dump($cstrong);
+    echo PHP_EOL;
+}
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+Comprimentos: Bytes: 1 e Hex: 2
+string(2) "42"
+bool(true)
+
+Comprimentos: Bytes: 2 e Hex: 4
+string(4) "dc6e"
+bool(true)
+
+Comprimentos: Bytes: 3 e Hex: 6
+string(6) "288591"
+bool(true)
+
+Comprimentos: Bytes: 4 e Hex: 8
+string(8) "ab86d144"
+bool(true)
+
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>random_bytes</function></member>
+   <member><function>bin2hex</function></member>
+   <member><function>crypt</function></member>
+   <member><function>random_int</function></member>
+  </simplelist>
+ </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
+-->

reference/openssl/functions/openssl-seal.xml

@@ -0,0 +1,207 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 110ac43250fdb3531fe26d4d29292e33df7855e8 Maintainer: leonardolara Status: ready -->
+<refentry xml:id="function.openssl-seal" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>openssl_seal</refname>
+  <refpurpose>Sela (criptografa) dados</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type class="union"><type>int</type><type>false</type></type><methodname>openssl_seal</methodname>
+   <methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>data</parameter></methodparam>
+   <methodparam><type>string</type><parameter role="reference">sealed_data</parameter></methodparam>
+   <methodparam><type>array</type><parameter role="reference">encrypted_keys</parameter></methodparam>
+   <methodparam><type>array</type><parameter>public_key</parameter></methodparam>
+   <methodparam><type>string</type><parameter>cipher_algo</parameter></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter role="reference">iv</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+   <function>openssl_seal</function> sela (criptografa) os dados de <parameter>data</parameter> usando o
+   algoritmo de criptografia <parameter>cipher_algo</parameter> com uma chave secreta gerada aleatoriamente. A chave é
+   então criptografada com cada uma das chaves públicas no array <parameter>public_key</parameter>,
+   e cada chave de envelope criptografada é retornada em <parameter>encrypted_keys</parameter>. Isso permite
+   que dados selados sejam enviados a vários destinatários (desde que suas chaves públicas estejam disponíveis). Cada
+   destinatário deve receber os dados selados e a chave do envelope que foi criptografada com a
+   chave pública do destinatário. O IV (Vetor de Inicialização) é gerado e seu valor é retornado em
+   <parameter>iv</parameter>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>data</parameter></term>
+     <listitem>
+      <para>
+       Os dados a serem selados.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>sealed_data</parameter></term>
+     <listitem>
+      <para>
+       Os dados selados.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>encrypted_keys</parameter></term>
+     <listitem>
+      <para>
+       Array de chaves criptografadas.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>public_key</parameter></term>
+     <listitem>
+      <para>
+       Array de instâncias de <classname>OpenSSLAsymmetricKey</classname> contendo chaves públicas.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>cipher_algo</parameter></term>
+     <listitem>
+      <para>
+       O método de criptografia.
+       <caution>
+        <simpara>
+         O valor padrão para versões do PHP anteriores a 8.0 é (<literal>'RC4'</literal>) que é
+         considerado inseguro. É altamente recomendável especificar explicitamente um método de
+         criptografia seguro.
+        </simpara>
+       </caution>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>iv</parameter></term>
+     <listitem>
+      <para>
+       O vetor de inicialização para descriptografia de <parameter>data</parameter>. É necessário se
+       o método de criptografia exigir IV. Isso pode ser descoberto chamando
+       <function>openssl_cipher_iv_length</function> com <parameter>cipher_algo</parameter>.
+      </para>
+      <caution>
+       <simpara>
+        O IV não pode ser definido explicitamente. Qualquer valor definido nele é substituído por um valor gerado
+        aleatoriamente.
+       </simpara>
+      </caution>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Retorna o comprimento dos dados selados em caso de sucesso ou &false; em caso de erro.
+   Se for bem-sucedido, os dados selados serão retornados em
+   <parameter>sealed_data</parameter> e as chaves do envelope em
+   <parameter>encrypted_keys</parameter>.
+  </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>public_key</parameter> agora aceita um &array; de
+       instâncias de <classname>OpenSSLAsymmetricKey</classname>;
+       anteriormente, um &array; de &resource;s do tipo <literal>OpenSSL key</literal>
+       era aceito.
+      </entry>
+     </row>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       <parameter>cipher_algo</parameter> não é mais um parâmetro opcional.
+      </entry>
+     </row>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       <parameter>iv</parameter> agora pode ser nulo.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Exemplo de <function>openssl_seal</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Presume-se que $data contenha os dados a serem selados
+$data = "test";
+
+// busca chaves públicas
+$pk1 = openssl_get_publickey("file://cert1.pem");
+$pk2 = openssl_get_publickey("file://cert2.pem");
+
+// sela a mensagem, apenas os proprietários de $pk1 e $pk2 podem descriptografar $sealed com as chaves
+// $ekeys[0] e $ekeys[1] respectivamente.
+if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
+    // possivelmente armazena os valores $sealed e $iv e usa mais tarde em openssl_open
+    echo "sucesso\n";
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>openssl_open</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
+-->