mcrypt-encrypt.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5fabd07880ab15b0ad2cf7eb055c7c2b36d7120f Maintainer: yuanyuqiang Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<refentry xml:id="function.mcrypt-encrypt" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mcrypt_encrypt</refname>
  <refpurpose>使用给定参数加密明文</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
  &warn.deprecated.function-7-1-0.removed-7-2-0;
 </refsynopsisdiv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>false</type></type><methodname>mcrypt_encrypt</methodname>
   <methodparam><type>string</type><parameter>cipher</parameter></methodparam>
   <methodparam><type>string</type><parameter>key</parameter></methodparam>
   <methodparam><type>string</type><parameter>data</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>iv</parameter></methodparam>
  </methodsynopsis>
  <para>
   加密数据并返回密文。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>cipher</parameter></term>
     <listitem>
      &mcrypt.parameter.cipher;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>key</parameter></term>
     <listitem>
      <para>
       加密密钥。
       如果密钥长度不是该算法所能够支持的有效长度，则函数将会发出警告并返回 &false;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>data</parameter></term>
     <listitem>
      <para>
       使用给定的 <parameter>cipher</parameter> 和 <parameter>mode</parameter>
       加密的数据。
       如果数据长度不是 n*分组大小，则在其后使用 '<literal>\0</literal>' 补齐。
      </para>
      <para>
       返回的密文长度可能比 <parameter>data</parameter> 
       更大。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      &mcrypt.parameter.mode;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>iv</parameter></term>
     <listitem>
      &mcrypt.parameter.iv.strict;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   以字符串方式返回密文，&return.falseforfailure;。
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>mcrypt_encrypt</function> 示例</title>
    <programlisting role="php">
<![CDATA[
<?php
    # --- 加密 ---

    # 密钥应该是随机的二进制数据，
    # 开始使用 scrypt, bcrypt 或 PBKDF2 将一个字符串转换成一个密钥
    # 密钥是 16 进制字符串格式
    $key = pack('H*', "bcb04b7e103a0cd8b54763051cef08bc55abe029fdebae5e1d417e2ffb2a00a3");
    
    # 显示 AES-128, 192, 256 对应的密钥长度：
    #16，24，32 字节。
    $key_size =  strlen($key);
    echo "Key size: " . $key_size . "\n";
    
    $plaintext = "This string was AES-256 / CBC / ZeroBytePadding encrypted.";

    # 为 CBC 模式创建随机的初始向量
    $iv_size = mcrypt_get_iv_size(MCRYPT_RIJNDAEL_128, MCRYPT_MODE_CBC);
    $iv = mcrypt_create_iv($iv_size, MCRYPT_RAND);
    

    # 创建和 AES 兼容的密文（Rijndael 分组大小 = 128）
    # 仅适用于编码后的输入不是以 00h 结尾的
    # （因为默认是使用 0 来补齐数据）
    $ciphertext = mcrypt_encrypt(MCRYPT_RIJNDAEL_128, $key,
                                 $plaintext, MCRYPT_MODE_CBC, $iv);

    # 将初始向量附加在密文之后，以供解密时使用
    $ciphertext = $iv . $ciphertext;
    
    # 对密文进行 base64 编码
    $ciphertext_base64 = base64_encode($ciphertext);

    echo  $ciphertext_base64 . "\n";

    # === 警告 ===

    # 密文并未进行完整性和可信度保护，
    # 所以可能遭受 Padding Oracle 攻击。
    
    # --- 解密 ---
    
    $ciphertext_dec = base64_decode($ciphertext_base64);
    
    # 初始向量大小，可以通过 mcrypt_get_iv_size() 来获得
    $iv_dec = substr($ciphertext_dec, 0, $iv_size);
    
    # 获取除初始向量外的密文
    $ciphertext_dec = substr($ciphertext_dec, $iv_size);

    # 可能需要从明文末尾移除 0
    $plaintext_dec = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key,
                                    $ciphertext_dec, MCRYPT_MODE_CBC, $iv_dec);
    
    echo  $plaintext_dec . "\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Key size: 32
ENJW8mS2KaJoNB5E5CoSAAu0xARgsR1bdzFWpEn+poYw45q+73az5kYi4j+0haevext1dGrcW8Qi59txfCBV8BBj3bzRP3dFCp3CPQSJ8eU=
This string was AES-256 / CBC / ZeroBytePadding encrypted.
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mcrypt_decrypt</function></member>
    <member><function>mcrypt_module_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
-->