<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 7a016103e0d568448f5985dfd945092d69d5d59c Maintainer: duanxiaoqiang Status: ready -->

<!-- CREDITS: mowangjuanzi, Luffy -->

<refentry xml:id="function.openssl-encrypt" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>openssl_encrypt</refname>

<refpurpose>加密数据</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>string</type><type>false</type></type><methodname>openssl_encrypt</methodname>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>data</parameter></methodparam>

<methodparam><type>string</type><parameter>cipher_algo</parameter></methodparam>

<methodparam><modifier role="attribute">#[\SensitiveParameter]</modifier><type>string</type><parameter>passphrase</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>iv</parameter><initializer>""</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter role="reference">tag</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter>aad</parameter><initializer>""</initializer></methodparam>

<methodparam choice="opt"><type>int</type><parameter>tag_length</parameter><initializer>16</initializer></methodparam>

</methodsynopsis>

<para>

以指定的方式和密码短语加密数据，返回原始或 base64 编码后的字符串。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>data</parameter></term>

<listitem>

<para>

待加密的明文信息数据。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>cipher_algo</parameter></term>

<listitem>

<para>

密码学方式。<function>openssl_get_cipher_methods</function> 可获取有效密码方式列表。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>passphrase</parameter></term>

<listitem>

<para>

密码短语。若 passphrase 比预期长度短，将静默用 <literal>NUL</literal> 填充；

若比预期长度更长，将静默截断。

</para>

<caution>

<simpara>

正如其名称所示，passphrase 没有用于密钥导出函数。唯一的操作是用 <literal>NUL</literal> 字符填充，或者如果长度与预期不同则截断。

</simpara>

</caution>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>options</parameter></term>

<listitem>

<para>

<parameter>options</parameter> 是以下标记的按位或：

<constant>OPENSSL_RAW_DATA</constant> 和

<constant>OPENSSL_ZERO_PADDING</constant>

或 <constant>OPENSSL_DONT_ZERO_PAD_KEY</constant>。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>iv</parameter></term>

<listitem>

<para>

非 &null; 的初始化向量。如果 IV 比预期短，则用 <literal>NUL</literal> 字符填充并发出警告；如果密码短语比预期长，则将其截断并发出警告。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>tag</parameter></term>

<listitem>

<para>

使用 AEAD 密码模式（GCM 或 CCM）时传引用的验证标签。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>aad</parameter></term>

<listitem>

<para>

附加的验证数据。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>tag_length</parameter></term>

<listitem>

<para>

验证 <parameter>tag</parameter> 的长度。GCM 模式时，它的范围是 4 到 16。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

成功时返回加密后的字符串，&return.falseforfailure;。

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

<parameter>cipher_algo</parameter> 传入未知算法时，产生 <constant>E_WARNING</constant> 级别的错误。

</para>

<para>

<parameter>iv</parameter> 传入空字符串时产生 <constant>E_WARNING</constant> 级别的错误。

</para>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>7.1.0</entry>

<entry>增加了 <parameter>tag</parameter>、<parameter>aad</parameter>、<parameter>tag_length</parameter> 参数</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>PHP 7.1 之前的 GCM 模式的 AES 认证加密示例</title>

<programlisting role="php">

<![CDATA[

<?php

//$key should have been previously generated in a cryptographically safe way, like openssl_random_pseudo_bytes

$plaintext = "message to be encrypted";

$cipher = "aes-128-gcm";

if (in_array($cipher, openssl_get_cipher_methods()))

{

$ivlen = openssl_cipher_iv_length($cipher);

$iv = openssl_random_pseudo_bytes($ivlen);

$ciphertext = openssl_encrypt($plaintext, $cipher, $key, $options=0, $iv, $tag);

//store $cipher, $iv, and $tag for decryption later

$original_plaintext = openssl_decrypt($ciphertext, $cipher, $key, $options=0, $iv, $tag);

echo $original_plaintext."\n";

}

?>

]]>

</programlisting>

</example>

<example>

<title>PHP 5.6+ 的 AES 认证加密例子</title>

<programlisting role="php">

<![CDATA[

<?php

//$key previously generated safely, ie: openssl_random_pseudo_bytes

$plaintext = "message to be encrypted";

$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");

$iv = openssl_random_pseudo_bytes($ivlen);

$ciphertext_raw = openssl_encrypt($plaintext, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);

$hmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);

$ciphertext = base64_encode( $iv.$hmac.$ciphertext_raw );

//decrypt later....

$c = base64_decode($ciphertext);

$ivlen = openssl_cipher_iv_length($cipher="AES-128-CBC");

$iv = substr($c, 0, $ivlen);

$hmac = substr($c, $ivlen, $sha2len=32);

$ciphertext_raw = substr($c, $ivlen+$sha2len);

$original_plaintext = openssl_decrypt($ciphertext_raw, $cipher, $key, $options=OPENSSL_RAW_DATA, $iv);

$calcmac = hash_hmac('sha256', $ciphertext_raw, $key, $as_binary=true);

if (hash_equals($hmac, $calcmac))// timing attack safe comparison

{

echo $original_plaintext."\n";

}

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>openssl_decrypt</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

-->