Author: paul
Date: 2006-01-22 21:08:12 +0100 (Sun, 22 Jan 2006)
New Revision: 989
Log:
r6561@frost: paul | 2006-01-22 13:03:02 -0600
General revisions.
Modified:
trunk/
trunk/refman-4.1/functions.xml
trunk/refman-5.0/functions.xml
trunk/refman-5.1/functions.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6560
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2396
+ b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6561
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2396
Modified: trunk/refman-4.1/functions.xml
===================================================================
--- trunk/refman-4.1/functions.xml 2006-01-22 20:07:59 UTC (rev 988)
+++ trunk/refman-4.1/functions.xml 2006-01-22 20:08:12 UTC (rev 989)
@@ -11587,16 +11587,21 @@
<remark role="help-category" condition="Encryption Functions@Functions"/>
<para>
- The functions in this section encrypt and decrypt data values.
- If you want to store results from an encryption function that
- might contain arbitrary byte values, use a
- <literal>BLOB</literal> column rather than a
- <literal>CHAR</literal> or <literal>VARCHAR</literal> column to
- avoid potential problems with trailing space removal that would
- change data values.
+ The functions in this section perform encryption and decryption,
+ and compression and uncompression.
</para>
<para>
+ <emphasis role="bold">Note</emphasis>: The encryption and
+ compression functions return binary strings. For many of these
+ functions, the result might contain arbitrary byte values. If
+ you want to store these results, use a <literal>BLOB</literal>
+ column rather than a <literal>CHAR</literal> or
+ <literal>VARCHAR</literal> column to avoid potential problems
+ with trailing space removal that would change data values.
+ </para>
+
+ <para>
<emphasis role="bold">Note</emphasis>: Exploits for the MD5 and
SHA-1 algorithms have become known. You may wish to consider
using one of the other encryption functions described in this
@@ -11642,19 +11647,24 @@
</para>
<para>
- The input arguments may be any length. If either argument is
- <literal>NULL</literal>, the result of this function is also
- <literal>NULL</literal>.
+ <literal>AES_ENCRYPT()</literal> encrypts a string and
+ returns a binary string. <literal>AES_DESCRIPT()</literal>
+ descrypts the encrypted string and returns the original
+ string. The input arguments may be any length. If either
+ argument is <literal>NULL</literal>, the result of this
+ function is also <literal>NULL</literal>.
</para>
<para>
Because AES is a block-level algorithm, padding is used to
encode uneven length strings and so the result string length
- may be calculated as <literal>16 *
- (trunc(<replaceable>string_length</replaceable> / 16) +
- 1)</literal>.
+ may be calculated using this formula:
</para>
+<programlisting>
+16 × (trunc(<replaceable>string_length</replaceable> / 16) + 1)
+</programlisting>
+
<para>
If <literal>AES_DECRYPT()</literal> detects invalid data or
incorrect padding, it returns <literal>NULL</literal>.
@@ -11812,8 +11822,7 @@
<para>
The result is a binary string of the same length as
- <replaceable>str</replaceable>. If you want to save it in a
- column, use a <literal>BLOB</literal> data type.
+ <replaceable>str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -11838,8 +11847,8 @@
<para>
Decrypts a string encrypted with
- <literal>DES_ENCRYPT()</literal>. On error, this function
- returns <literal>NULL</literal>.
+ <literal>DES_ENCRYPT()</literal>. If an error occurs, this
+ function returns <literal>NULL</literal>.
</para>
<para>
@@ -11897,8 +11906,7 @@
<para>
Encrypts the string with the given key using the Triple-DES
- algorithm. On error, this function returns
- <literal>NULL</literal>.
+ algorithm.
</para>
<remark role="help-description-end"/>
@@ -11947,7 +11955,9 @@
<para>
The return string is a binary string where the first
- character is <literal>CHAR(128 | key_num)</literal>.
+ character is <literal>CHAR(128 | key_num)</literal>. If an
+ error occurs, <literal>DES_ENCRYPT()</literal> returns
+ <literal>NULL</literal>.
</para>
<para>
@@ -11957,12 +11967,13 @@
</para>
<para>
- The string length for the result is
- <literal><replaceable>new_len</replaceable> =
- <replaceable>orig_len</replaceable> +
- (8-(<replaceable>orig_len</replaceable> % 8))+1</literal>.
+ The string length for the result is given by this formula:
</para>
+<programlisting>
+<replaceable>new_len</replaceable> = <replaceable>orig_len</replaceable> + (8 - (<replaceable>orig_len</replaceable> % 8)) + 1
+</programlisting>
+
<para>
Each line in the DES key file has the following format:
</para>
@@ -11974,12 +11985,12 @@
</programlisting>
<para>
- Each <replaceable>key_num</replaceable> must be a number in
- the range from <literal>0</literal> to <literal>9</literal>.
- Lines in the file may be in any order.
+ Each <replaceable>key_num</replaceable> value must be a
+ number in the range from <literal>0</literal> to
+ <literal>9</literal>. Lines in the file may be in any order.
<replaceable>des_key_str</replaceable> is the string that is
- used to encrypt the message. Between the number and the key
- there should be at least one space. The first key is the
+ used to encrypt the message. There should be at least one
+ space between the number and the key. The first key is the
default key that is used if you do not specify any key
argument to <literal>DES_ENCRYPT()</literal>
</para>
@@ -11998,8 +12009,8 @@
</para>
<programlisting>
-mysql> <userinput>SELECT customer_address FROM customer_table WHERE</userinput>
- crypted_credit_card = DES_ENCRYPT('credit_card_number');
+mysql> <userinput>SELECT customer_address FROM customer_table </userinput>
+ > <userinput>WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');</userinput>
</programlisting>
<para>
@@ -12025,10 +12036,10 @@
<remark role="help-description-begin"/>
<para>
- Encrypt <replaceable>str</replaceable> using the Unix
- <literal>crypt()</literal> system call. The
- <replaceable>salt</replaceable> argument should be a string
- with two characters. (As of MySQL 3.22.16,
+ Encrypts <replaceable>str</replaceable> using the Unix
+ <literal>crypt()</literal> system call and returns a binary
+ string. The <replaceable>salt</replaceable> argument should
+ be a string with two characters. (As of MySQL 3.22.16,
<replaceable>salt</replaceable> may be longer than two
characters.) If no <replaceable>salt</replaceable> argument
is given, a random value is used.
@@ -12094,8 +12105,8 @@
</programlisting>
<para>
- This is the "RSA Data Security, Inc. MD5 Message-Digest
- Algorithm."
+ This is the <quote>RSA Data Security, Inc. MD5
+ Message-Digest Algorithm.</quote>
</para>
<para>
@@ -12138,10 +12149,10 @@
<literal>PASSWORD()</literal> was changed to improve
security. <literal>OLD_PASSWORD()</literal> returns the
value of the pre-4.1 implementation of
- <literal>PASSWORD()</literal>, and is intended to permit you
- to reset passwords for any pre-4.1 clients that need to
- connect to your version ¤t-series; MySQL server
- without locking them out. See
+ <literal>PASSWORD()</literal> as a binary string, and is
+ intended to permit you to reset passwords for any pre-4.1
+ clients that need to connect to your version
+ ¤t-series; MySQL server without locking them out. See
<xref linkend="password-hashing"/>.
</para>
@@ -12167,8 +12178,8 @@
<para>
Calculates and returns a password string from the plaintext
- password <replaceable>str</replaceable>, or
- <literal>NULL</literal> if the argument was
+ password <replaceable>str</replaceable> and returns a binary
+ string, or <literal>NULL</literal> if the argument was
<literal>NULL</literal>. This is the function that is used
for encrypting MySQL passwords for storage in the
<literal>Password</literal> column of the
@@ -12241,7 +12252,7 @@
<para>
Calculates an SHA-1 160-bit checksum for the string, as
described in RFC 3174 (Secure Hash Algorithm). The value is
- returned as a string of 40 hex digits, or
+ returned as a binary string of 40 hex digits, or
<literal>NULL</literal> if the argument was
<literal>NULL</literal>. One of the possible uses for this
function is as a hash key. You can also use it as a
Modified: trunk/refman-5.0/functions.xml
===================================================================
--- trunk/refman-5.0/functions.xml 2006-01-22 20:07:59 UTC (rev 988)
+++ trunk/refman-5.0/functions.xml 2006-01-22 20:08:12 UTC (rev 989)
@@ -11573,8 +11573,8 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT BIT_COUNT(29);</userinput>
- -> 4
+mysql> <userinput>SELECT BIT_COUNT(29), BIT_COUNT(b'101010');</userinput>
+ -> 4, 3
</programlisting>
</listitem>
@@ -11598,16 +11598,22 @@
<remark role="help-category" condition="Encryption Functions@Functions"/>
<para>
- The functions in this section encrypt and decrypt data values.
- If you want to store results from an encryption function that
- might contain arbitrary byte values, use a
- <literal>BLOB</literal> column rather than a
- <literal>CHAR</literal> or (before MySQL 5.0.3)
- <literal>VARCHAR</literal> column to avoid potential problems
- with trailing space removal that would change data values.
+ The functions in this section perform encryption and decryption,
+ and compression and uncompression.
</para>
<para>
+ <emphasis role="bold">Note</emphasis>: The encryption and
+ compression functions return binary strings. For many of these
+ functions, the result might contain arbitrary byte values. If
+ you want to store these results, use a <literal>BLOB</literal>
+ column rather than a <literal>CHAR</literal> or (before MySQL
+ 5.0.3) <literal>VARCHAR</literal> column to avoid potential
+ problems with trailing space removal that would change data
+ values.
+ </para>
+
+ <para>
<emphasis role="bold">Note</emphasis>: Exploits for the MD5 and
SHA-1 algorithms have become known. You may wish to consider
using one of the other encryption functions described in this
@@ -11653,19 +11659,24 @@
</para>
<para>
- The input arguments may be any length. If either argument is
- <literal>NULL</literal>, the result of this function is also
- <literal>NULL</literal>.
+ <literal>AES_ENCRYPT()</literal> encrypts a string and
+ returns a binary string. <literal>AES_DESCRIPT()</literal>
+ descrypts the encrypted string and returns the original
+ string. The input arguments may be any length. If either
+ argument is <literal>NULL</literal>, the result of this
+ function is also <literal>NULL</literal>.
</para>
<para>
Because AES is a block-level algorithm, padding is used to
encode uneven length strings and so the result string length
- may be calculated as <literal>16 *
- (trunc(<replaceable>string_length</replaceable> / 16) +
- 1)</literal>.
+ may be calculated using this formula:
</para>
+<programlisting>
+16 × (trunc(<replaceable>string_length</replaceable> / 16) + 1)
+</programlisting>
+
<para>
If <literal>AES_DECRYPT()</literal> detects invalid data or
incorrect padding, it returns <literal>NULL</literal>.
@@ -11819,8 +11830,7 @@
<para>
The result is a binary string of the same length as
- <replaceable>str</replaceable>. If you want to save it in a
- column, use a <literal>BLOB</literal> data type.
+ <replaceable>str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -11845,8 +11855,8 @@
<para>
Decrypts a string encrypted with
- <literal>DES_ENCRYPT()</literal>. On error, this function
- returns <literal>NULL</literal>.
+ <literal>DES_ENCRYPT()</literal>. If an error occurs, this
+ function returns <literal>NULL</literal>.
</para>
<para>
@@ -11900,8 +11910,7 @@
<para>
Encrypts the string with the given key using the Triple-DES
- algorithm. On error, this function returns
- <literal>NULL</literal>.
+ algorithm.
</para>
<remark role="help-description-end"/>
@@ -11950,7 +11959,9 @@
<para>
The return string is a binary string where the first
- character is <literal>CHAR(128 | key_num)</literal>.
+ character is <literal>CHAR(128 | key_num)</literal>. If an
+ error occurs, <literal>DES_ENCRYPT()</literal> returns
+ <literal>NULL</literal>.
</para>
<para>
@@ -11960,12 +11971,13 @@
</para>
<para>
- The string length for the result is
- <literal><replaceable>new_len</replaceable> =
- <replaceable>orig_len</replaceable> +
- (8-(<replaceable>orig_len</replaceable> % 8))+1</literal>.
+ The string length for the result is given by this formula:
</para>
+<programlisting>
+<replaceable>new_len</replaceable> = <replaceable>orig_len</replaceable> + (8 - (<replaceable>orig_len</replaceable> % 8)) + 1
+</programlisting>
+
<para>
Each line in the DES key file has the following format:
</para>
@@ -11977,12 +11989,12 @@
</programlisting>
<para>
- Each <replaceable>key_num</replaceable> must be a number in
- the range from <literal>0</literal> to <literal>9</literal>.
- Lines in the file may be in any order.
+ Each <replaceable>key_num</replaceable> value must be a
+ number in the range from <literal>0</literal> to
+ <literal>9</literal>. Lines in the file may be in any order.
<replaceable>des_key_str</replaceable> is the string that is
- used to encrypt the message. Between the number and the key
- there should be at least one space. The first key is the
+ used to encrypt the message. There should be at least one
+ space between the number and the key. The first key is the
default key that is used if you do not specify any key
argument to <literal>DES_ENCRYPT()</literal>
</para>
@@ -12002,7 +12014,7 @@
<programlisting>
mysql> <userinput>SELECT customer_address FROM customer_table </userinput>
- > WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');
+ > <userinput>WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');</userinput>
</programlisting>
</listitem>
@@ -12024,10 +12036,10 @@
<remark role="help-description-begin"/>
<para>
- Encrypt <replaceable>str</replaceable> using the Unix
- <literal>crypt()</literal> system call. The
- <replaceable>salt</replaceable> argument should be a string
- with at least two characters. If no
+ Encrypts <replaceable>str</replaceable> using the Unix
+ <literal>crypt()</literal> system call and returns a binary
+ string. The <replaceable>salt</replaceable> argument should
+ be a string with at least two characters. If no
<replaceable>salt</replaceable> argument is given, a random
value is used.
</para>
@@ -12092,8 +12104,8 @@
</programlisting>
<para>
- This is the "RSA Data Security, Inc. MD5 Message-Digest
- Algorithm."
+ This is the <quote>RSA Data Security, Inc. MD5
+ Message-Digest Algorithm.</quote>
</para>
<para>
@@ -12132,10 +12144,10 @@
changed to improve security.
<literal>OLD_PASSWORD()</literal> returns the value of the
old (pre-4.1) implementation of
- <literal>PASSWORD()</literal>, and is intended to permit you
- to reset passwords for any pre-4.1 clients that need to
- connect to your version ¤t-series; MySQL server
- without locking them out. See
+ <literal>PASSWORD()</literal> as a binary string, and is
+ intended to permit you to reset passwords for any pre-4.1
+ clients that need to connect to your version
+ ¤t-series; MySQL server without locking them out. See
<xref linkend="password-hashing"/>.
</para>
@@ -12161,8 +12173,8 @@
<para>
Calculates and returns a password string from the plaintext
- password <replaceable>str</replaceable>, or
- <literal>NULL</literal> if the argument was
+ password <replaceable>str</replaceable> and returns a binary
+ string, or <literal>NULL</literal> if the argument was
<literal>NULL</literal>. This is the function that is used
for encrypting MySQL passwords for storage in the
<literal>Password</literal> column of the
@@ -12235,7 +12247,7 @@
<para>
Calculates an SHA-1 160-bit checksum for the string, as
described in RFC 3174 (Secure Hash Algorithm). The value is
- returned as a string of 40 hex digits, or
+ returned as a binary string of 40 hex digits, or
<literal>NULL</literal> if the argument was
<literal>NULL</literal>. One of the possible uses for this
function is as a hash key. You can also use it as a
Modified: trunk/refman-5.1/functions.xml
===================================================================
--- trunk/refman-5.1/functions.xml 2006-01-22 20:07:59 UTC (rev 988)
+++ trunk/refman-5.1/functions.xml 2006-01-22 20:08:12 UTC (rev 989)
@@ -12001,8 +12001,8 @@
<remark role="help-example"/>
<programlisting>
-mysql> <userinput>SELECT BIT_COUNT(29);</userinput>
- -> 4
+mysql> <userinput>SELECT BIT_COUNT(29), BIT_COUNT(b'101010');</userinput>
+ -> 4, 3
</programlisting>
</listitem>
@@ -12026,16 +12026,21 @@
<remark role="help-category" condition="Encryption Functions@Functions"/>
<para>
- The functions in this section encrypt and decrypt data values.
- If you want to store results from an encryption function that
- might contain arbitrary byte values, use a
- <literal>BLOB</literal> column rather than a
- <literal>CHAR</literal> or <literal>VARCHAR</literal> column to
- avoid potential problems with trailing space removal that would
- change data values.
+ The functions in this section perform encryption and decryption,
+ and compression and uncompression.
</para>
<para>
+ <emphasis role="bold">Note</emphasis>: The encryption and
+ compression functions return binary strings. For many of these
+ functions, the result might contain arbitrary byte values. If
+ you want to store these results, use a <literal>BLOB</literal>
+ column rather than a <literal>CHAR</literal> or
+ <literal>VARCHAR</literal> column to avoid potential problems
+ with trailing space removal that would change data values.
+ </para>
+
+ <para>
<emphasis role="bold">Note</emphasis>: Exploits for the MD5 and
SHA-1 algorithms have become known. You may wish to consider
using one of the other encryption functions described in this
@@ -12081,19 +12086,24 @@
</para>
<para>
- The input arguments may be any length. If either argument is
- <literal>NULL</literal>, the result of this function is also
- <literal>NULL</literal>.
+ <literal>AES_ENCRYPT()</literal> encrypts a string and
+ returns a binary string. <literal>AES_DESCRIPT()</literal>
+ descrypts the encrypted string and returns the original
+ string. The input arguments may be any length. If either
+ argument is <literal>NULL</literal>, the result of this
+ function is also <literal>NULL</literal>.
</para>
<para>
Because AES is a block-level algorithm, padding is used to
encode uneven length strings and so the result string length
- may be calculated as <literal>16 *
- (trunc(<replaceable>string_length</replaceable> / 16) +
- 1)</literal>.
+ may be calculated using this formula:
</para>
+<programlisting>
+16 × (trunc(<replaceable>string_length</replaceable> / 16) + 1)
+</programlisting>
+
<para>
If <literal>AES_DECRYPT()</literal> detects invalid data or
incorrect padding, it returns <literal>NULL</literal>.
@@ -12247,8 +12257,7 @@
<para>
The result is a binary string of the same length as
- <replaceable>str</replaceable>. If you want to save it in a
- column, use a <literal>BLOB</literal> data type.
+ <replaceable>str</replaceable>.
</para>
<remark role="help-description-end"/>
@@ -12273,8 +12282,8 @@
<para>
Decrypts a string encrypted with
- <literal>DES_ENCRYPT()</literal>. On error, this function
- returns <literal>NULL</literal>.
+ <literal>DES_ENCRYPT()</literal>. If an error occurs, this
+ function returns <literal>NULL</literal>.
</para>
<para>
@@ -12328,8 +12337,7 @@
<para>
Encrypts the string with the given key using the Triple-DES
- algorithm. On error, this function returns
- <literal>NULL</literal>.
+ algorithm.
</para>
<remark role="help-description-end"/>
@@ -12378,7 +12386,9 @@
<para>
The return string is a binary string where the first
- character is <literal>CHAR(128 | key_num)</literal>.
+ character is <literal>CHAR(128 | key_num)</literal>. If an
+ error occurs, <literal>DES_ENCRYPT()</literal> returns
+ <literal>NULL</literal>.
</para>
<para>
@@ -12388,12 +12398,13 @@
</para>
<para>
- The string length for the result is
- <literal><replaceable>new_len</replaceable> =
- <replaceable>orig_len</replaceable> +
- (8-(<replaceable>orig_len</replaceable> % 8))+1</literal>.
+ The string length for the result is given by this formula:
</para>
+<programlisting>
+<replaceable>new_len</replaceable> = <replaceable>orig_len</replaceable> + (8 - (<replaceable>orig_len</replaceable> % 8)) + 1
+</programlisting>
+
<para>
Each line in the DES key file has the following format:
</para>
@@ -12405,12 +12416,12 @@
</programlisting>
<para>
- Each <replaceable>key_num</replaceable> must be a number in
- the range from <literal>0</literal> to <literal>9</literal>.
- Lines in the file may be in any order.
+ Each <replaceable>key_num</replaceable> value must be a
+ number in the range from <literal>0</literal> to
+ <literal>9</literal>. Lines in the file may be in any order.
<replaceable>des_key_str</replaceable> is the string that is
- used to encrypt the message. Between the number and the key
- there should be at least one space. The first key is the
+ used to encrypt the message. There should be at least one
+ space between the number and the key. The first key is the
default key that is used if you do not specify any key
argument to <literal>DES_ENCRYPT()</literal>
</para>
@@ -12430,7 +12441,7 @@
<programlisting>
mysql> <userinput>SELECT customer_address FROM customer_table </userinput>
- > WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');
+ > <userinput>WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');</userinput>
</programlisting>
</listitem>
@@ -12452,10 +12463,10 @@
<remark role="help-description-begin"/>
<para>
- Encrypt <replaceable>str</replaceable> using the Unix
- <literal>crypt()</literal> system call. The
- <replaceable>salt</replaceable> argument should be a string
- with at least two characters. If no
+ Encrypts <replaceable>str</replaceable> using the Unix
+ <literal>crypt()</literal> system call and returns a binary
+ string. The <replaceable>salt</replaceable> argument should
+ be a string with at least two characters. If no
<replaceable>salt</replaceable> argument is given, a random
value is used.
</para>
@@ -12520,8 +12531,8 @@
</programlisting>
<para>
- This is the "RSA Data Security, Inc. MD5 Message-Digest
- Algorithm."
+ This is the <quote>RSA Data Security, Inc. MD5
+ Message-Digest Algorithm.</quote>
</para>
<para>
@@ -12560,10 +12571,10 @@
changed to improve security.
<literal>OLD_PASSWORD()</literal> returns the value of the
old (pre-4.1) implementation of
- <literal>PASSWORD()</literal>, and is intended to permit you
- to reset passwords for any pre-4.1 clients that need to
- connect to your version ¤t-series; MySQL server
- without locking them out. See
+ <literal>PASSWORD()</literal> as a binary string, and is
+ intended to permit you to reset passwords for any pre-4.1
+ clients that need to connect to your version
+ ¤t-series; MySQL server without locking them out. See
<xref linkend="password-hashing"/>.
</para>
@@ -12589,8 +12600,8 @@
<para>
Calculates and returns a password string from the plaintext
- password <replaceable>str</replaceable>, or
- <literal>NULL</literal> if the argument was
+ password <replaceable>str</replaceable> and returns a binary
+ string, or <literal>NULL</literal> if the argument was
<literal>NULL</literal>. This is the function that is used
for encrypting MySQL passwords for storage in the
<literal>Password</literal> column of the
@@ -12663,7 +12674,7 @@
<para>
Calculates an SHA-1 160-bit checksum for the string, as
described in RFC 3174 (Secure Hash Algorithm). The value is
- returned as a string of 40 hex digits, or
+ returned as a binary string of 40 hex digits, or
<literal>NULL</literal> if the argument was
<literal>NULL</literal>. One of the possible uses for this
function is as a hash key. You can also use it as a
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r989 - in trunk: . refman-4.1 refman-5.0 refman-5.1 | paul | 22 Jan |
