8000 Modify libpq's string-escaping routines to be aware of encoding consi… · postgrespro/postgres_cluster@515112f · GitHub
[go: up one dir, main page]
Skip to content

    • Commit 515112f

    Browse files
    tglsfdctglsfdc
    committed
    Modify libpq's string-escaping routines to be aware of encoding considerations
    and standard_conforming_strings. The encoding changes are needed for proper escaping in multibyte encodings, as per the SQL-injection vulnerabilities noted in CVE-2006-2313 and CVE-2006-2314. Concurrent fixes are being applied to the server to ensure that it rejects queries that may have been corrupted by attempted SQL injection, but this merely guarantees that unpatched clients will fail rather than allow injection. An actual fix requires changing the client-side code. While at it we have also fixed these routines to understand about standard_conforming_strings, so that the upcoming changeover to SQL-spec string syntax can be somewhat transparent to client code. Since the existing API of PQescapeString and PQescapeBytea provides no way to inform them which settings are in use, these functions are now deprecated in favor of new functions PQescapeStringConn and PQescapeByteaConn. The new functions take the PGconn to which the string will be sent as an additional parameter, and look inside the connection structure to determine what to do. So as to provide some functionality for clients using the old functions, libpq stores the latest encoding and standard_conforming_strings values received from the backend in static variables, and the old functions consult these variables. This will work reliably in clients using only one Postgres connection at a time, or even multiple connections if they all use the same encoding and string syntax settings; which should cover many practical scenarios. Clients that use homebrew escaping methods, such as PHP's addslashes() function or even hardwired regexp substitution, will require extra effort to fix :-(. It is strongly recommended that such code be replaced by use of PQescapeStringConn/PQescapeByteaConn if at all feasible.
    1 parent b3eb4ea commit 515112f

    File tree

    6 files changed

    +309
    -83
    lines changed

    6 files changed

    +309
    -83
    lines changed

    ‎doc/src/sgml/libpq.sgml

    Lines changed: 119 additions & 38 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1,4 +1,4 @@
    1-
    <!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.209 2006/05/17 21:50:54 momjian Exp $ -->
    1+
    <!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.210 2006/05/21 20:19:23 tgl Exp $ -->
    22

    33
    <chapter id="libpq">
    44
    <title><application>libpq</application> - C Library</title>
    @@ -2187,15 +2187,16 @@ It is not thread-safe.
    21872187
    <sect2 id="libpq-exec-escape-string">
    21882188
    <title>Escaping Strings for Inclusion in SQL Commands</title>
    21892189

    2190+
    <indexterm zone="libpq-exec-escape-string"><primary>PQescapeStringConn</></>
    21902191
    <indexterm zone="libpq-exec-escape-string"><primary>PQescapeString</></>
    21912192
    <indexterm zone="libpq-exec-escape-string"><primary>escaping strings</></>
    21922193

    21932194
    <para>
    2194-
    <function>PQescapeString</function> escapes a string for use within an SQL
    2195+
    <function>PQescapeStringConn</function> escapes a string for use within an SQL
    21952196
    command. This is useful when inserting data values as literal constants
    21962197
    in SQL commands. Certain characters (such as quotes and backslashes) must
    21972198
    be escaped to prevent them from being interpreted specially by the SQL parser.
    2198-
    <function>PQescapeString</> performs this operation.
    2199+
    <function>PQescapeStringConn</> performs this operation.
    21992200
    </para>
    22002201

    22012202
    <tip>
    @@ -2213,36 +2214,68 @@ value is passed as a separate parameter in <function>PQexecParams</> or
    22132214
    its sibling routines.
    22142215

    22152216
    <synopsis>
    2216-
    size_t PQescapeString (char *to, const char *from, size_t length);
    2217+
    size_t PQescapeStringConn (PGconn *conn,
    2218+
    char *to, const char *from, size_t length,
    2219+
    int *error);
    22172220
    </synopsis>
    22182221
    </para>
    22192222

    22202223
    <para>
    2224+
    <function>PQescapeStringConn</> writes an escaped
    2225+
    version of the <parameter>from</> string to the <parameter>to</>
    2226+
    buffer, escaping special characters so that they cannot cause any
    2227+
    harm, and adding a terminating zero byte. The single quotes that
    2228+
    must surround <productname>PostgreSQL</> string literals are not
    2229+
    included in the result string; they should be provided in the SQL
    2230+
    command that the result is inserted into.
    22212231
    The parameter <parameter>from</> points to the first character of the string
    22222232
    that is to be escaped, and the <parameter>length</> parameter gives the
    2223-
    number of characters in this string. A terminating zero byte is not
    2233+
    number of bytes in this string. A terminating zero byte is not
    22242234
    required, and should not be counted in <parameter>length</>. (If
    22252235
    a terminating zero byte is found before <parameter>length</> bytes are
    2226-
    processed, <function>PQescapeString</> stops at the zero; the behavior
    2236+
    processed, <function>PQescapeStringConn</> stops at the zero; the behavior
    22272237
    is thus rather like <function>strncpy</>.)
    22282238
    <parameter>to</> shall point to a
    2229-
    buffer that is able to hold at least one more character than twice
    2239+
    buffer that is able to hold at least one more byte than twice
    22302240
    the value of <parameter>length</>, otherwise the behavior is
    2231-
    undefined. A call to <function>PQescapeString</> writes an escaped
    2232-
    version of the <parameter>from</> string to the <parameter>to</>
    2233-
    buffer, replacing special characters so that they cannot cause any
    2234-
    harm, and adding a terminating zero byte. The single quotes that
    2235-
    must surround <productname>PostgreSQL</> string literals are not
    2236-
    included in the result string; they should be provided in the SQL
    2237-
    command that the result is inserted into.
    2241+
    undefined.
    2242+
    Behavior is likewise undefined if the <parameter>to</> and <parameter>from</>
    2243+
    strings overlap.
    2244+
    </para>
    2245+
    <para>
    2246+
    If the <parameter>error</> parameter is not NULL, then <literal>*error</>
    2247+
    is set to zero on success, nonzero on error. Presently the only possible
    2248+
    error conditions involve invalid multibyte encoding in the source string.
    2249+
    The output string is still generated on error, but it can be expected that
    2250+
    the server will reject it as malformed. On error, a suitable message is
    2251+
    stored in the <parameter>conn</> object, whether or not <parameter>error</>
    2252+
    is NULL.
    22382253
    </para>
    22392254
    <para>
    2240-
    <function>PQescapeString</> returns the number of characters written
    2255+
    <function>PQescapeStringConn</> returns the number of bytes written
    22412256
    to <parameter>to</>, not including the terminating zero byte.
    22422257
    </para>
    2258+
    22432259
    <para>
    2244-
    Behavior is undefined if the <parameter>to</> and <parameter>from</>
    2245-
    strings overlap.
    2260+
    <synopsis>
    2261+
    size_t PQescapeString (char *to, const char *from, size_t length);
    2262+
    </synopsis>
    2263+
    </para>
    2264+
    2265+
    <para>
    2266+
    <function>PQescapeString</> is an older, deprecated version of
    2267+
    <function>PQescapeStringConn</>; the difference is that it does not
    2268+
    take <parameter>conn</> or <parameter>error</> parameters. Because of this,
    2269+
    it cannot adjust its behavior depending on the connection properties (such as
    2270+
    character encoding) and therefore <emphasis>it may give the wrong results</>.
    2271+
    Also, it has no way to report error conditions.
    2272+
    </para>
    2273+
    <para>
    2274+
    <function>PQescapeString</> can be used safely in single-threaded client
    2275+
    programs that work with only one <productname>PostgreSQL</> connection at
    2276+
    a time (in this case it can find out what it needs to know <quote>behind the
    2277+
    scenes</>). In other contexts it is a security hazard and should be avoided
    2278+
    in favor of <function>PQescapeStringConn</>.
    22462279
    </para>
    22472280
    </sect2>
    22482281

    @@ -2257,16 +2290,17 @@ strings overlap.
    22572290

    22582291
    <variablelist>
    22592292
    <varlistentry>
    2260-
    <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</></></term>
    2293+
    <term><function>PQescapeByteaConn</function><indexterm><primary>PQescapeByteaConn</></></term>
    22612294
    <listitem>
    22622295
    <para>
    22632296
    Escapes binary data for use within an SQL command with the type
    2264-
    <type>bytea</type>. As with <function>PQescapeString</function>,
    2297+
    <type>bytea</type>. As with <function>PQescapeStringConn</function>,
    22652298
    this is only used when inserting data directly into an SQL command string.
    22662299
    <synopsis>
    2267-
    unsigned char *PQescapeBytea(const unsigned char *from,
    2268-
    size_t from_length,
    2269-
    size_t *to_length);
    2300+
    unsigned char *PQescapeByteaConn(PGconn *conn,
    2301+
    const unsigned char *from,
    2302+
    size_t from_length,
    2303+
    size_t *to_length);
    22702304
    </synopsis>
    22712305
    </para>
    22722306

    @@ -2276,10 +2310,10 @@ unsigned char *PQescapeBytea(const unsigned char *from,
    22762310
    of a <type>bytea</type> literal in an <acronym>SQL</acronym>
    22772311
    statement. In general, to escape a byte, it is converted into the
    22782312
    three digit octal number equal to the octet value, and preceded by
    2279-
    two backslashes. The single quote (<literal>'</>) and backslash
    2313+
    one or two backslashes. The single quote (<literal>'</>) and backslash
    22802314
    (<literal>\</>) characters have special alternative escape
    22812315
    sequences. See <xref linkend="datatype-binary"> for more
    2282-
    information. <function>PQescapeBytea</function> performs this
    2316+
    information. <function>PQescapeByteaConn</function> performs this
    22832317
    operation, escaping only the minimally required bytes.
    22842318
    </para>
    22852319

    @@ -2290,31 +2324,69 @@ unsigned char *PQescapeBytea(const unsigned char *from,
    22902324
    bytes in this binary string. (A terminating zero byte is
    22912325
    neither necessary nor counted.) The <parameter>to_length</parameter>
    22922326
    parameter points to a variable that will hold the resultant
    2293-
    escaped string length. The result string length includes the terminating
    2327+
    escaped string length. This result string length includes the terminating
    22942328
    zero byte of the result.
    22952329
    </para>
    22962330

    22972331
    <para>
    2298-
    <function>PQescapeBytea</> returns an escaped version of the
    2332+
    <function>PQescapeByteaConn</> returns an escaped version of the
    22992333
    <parameter>from</parameter> parameter binary string in memory
    2300-
    allocated with <function>malloc()</> (a null pointer is returned if
    2301-
    memory could not be allocated). This memory must be freed using
    2302-
    <function>PQfreemem</> when the result is no longer needed. The
    2334+
    allocated with <function>malloc()</>. This memory must be freed using
    2335+
    <function>PQfreemem()</> when the result is no longer needed. The
    23032336
    return string has all special characters replaced so that they can
    23042337
    be properly processed by the <productname>PostgreSQL</productname>
    23052338
    string literal parser, and the <type>bytea</type> input function. A
    23062339
    terminating zero byte is also added. The single quotes that must
    23072340
    surround <productname>PostgreSQL</productname> string literals are
    23082341
    not part of the result string.
    23092342
    </para>
    2343+
    2344+
    <para>
    2345+
    On error, a NULL pointer is returned, and a suitable error message
    2346+
    is stored in the <parameter>conn</> object. Currently, the only
    2347+
    possible error is insufficient memory for the result string.
    2348+
    </para>
    2349+
    </listitem>
    2350+
    </varlistentry>
    2351+
    2352+
    <varlistentry>
    2353+
    <term><function>PQescapeBytea</function><indexterm><primary>PQescapeBytea</></></term>
    2354+
    <listitem>
    2355+
    <para>
    2356+
    <function>PQescapeBytea</> is an older, deprecated version of
    2357+
    <function>PQescapeByteaConn</>.
    2358+
    <synopsis>
    2359+
    unsigned char *PQescapeBytea(const unsigned char *from,
    2360+
    size_t from_length,
    2361+
    size_t *to_length);
    2362+
    </synopsis>
    2363+
    </para>
    2364+
    2365+
    <para>
    2366+
    The only difference from <function>PQescapeByteaConn</> is that
    2367+
    <function>PQescapeBytea</> does not
    2368+
    take a <structname>PGconn</> parameter. Because of this, it cannot adjust
    2369+
    its behavior depending on the connection properties (in particular,
    2370+
    whether standard-conforming strings are enabled)
    2371+
    and therefore <emphasis>it may give the wrong results</>. Also, it
    2372+
    has no way to return an error message on failure.
    2373+
    </para>
    2374+
    2375+
    <para>
    2376+
    <function>PQescapeBytea</> can be used safely in single-threaded client
    2377+
    programs that work with only one <productname>PostgreSQL</> connection at
    2378+
    a time (in this case it can find out what it needs to know <quote>behind the
    2379+
    scenes</>). In other contexts it is a security hazard and should be
    2380+
    avoided in favor of <function>PQescapeByteaConn</>.
    2381+
    </para>
    23102382
    < F987 /listitem>
    23112383
    </varlistentry>
    23122384

    23132385
    <varlistentry>
    23142386
    <term><function>PQunescapeBytea</function><indexterm><primary>PQunescapeBytea</></></term>
    23152387
    <listitem>
    23162388
    <para>
    2317-
    Converts an escaped string representation of binary data into binary
    2389+
    Converts a string representation of binary data into binary
    23182390
    data &mdash; the reverse of <function>PQescapeBytea</function>.
    23192391
    This is needed when retrieving <type>bytea</type> data in text format,
    23202392
    but not when retrieving it in binary format.
    @@ -2324,16 +2396,24 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
    23242396
    </synopsis>
    23252397
    </para>
    23262398

    2327-
    <para>
    2328-
    The <parameter>from</parameter> parameter points to an escaped string
    2329-
    such as might be returned by <function>PQgetvalue</function> when applied to a
    2330-
    <type>bytea</type> column. <function>PQunescapeBytea</function> converts
    2331-
    this string representation into its binary representation.
    2399+
    <para>
    2400+
    The <parameter>from</parameter> parameter points to a string
    2401+
    such as might be returned by <function>PQgetvalue</function> when applied
    2402+
    to a <type>bytea</type> column. <function>PQunescapeBytea</function>
    2403+
    converts this string representation into its binary representation.
    23322404
    It returns a pointer to a buffer allocated with
    23332405
    <function>malloc()</function>, or null on error, and puts the size of
    23342406
    the buffer in <parameter>to_length</parameter>. The result must be
    23352407
    freed using <function>PQfreemem</> when it is no longer needed.
    23362408
    </para>
    2409+
    2410+
    <para>
    2411+
    This conversion is not exactly the inverse of
    2412+
    <function>PQescapeBytea</function>, because the string is not expected
    2413+
    to be <quote>escaped</> when received from <function>PQgetvalue</function>.
    2414+
    In particular this means there is no need for string quoting considerations,
    2415+
    and so no need for a <structname>PGconn</> parameter.
    2416+
    </para>
    23372417
    </listitem>
    23382418
    </varlistentry>
    23392419

    @@ -2349,6 +2429,7 @@ void PQfreemem(void *ptr);
    23492429

    23502430
    <para>
    23512431
    Frees memory allocated by <application>libpq</>, particularly
    2432+
    <function>PQescapeByteaConn</function>,
    23522433
    <function>PQescapeBytea</function>,
    23532434
    <function>PQunescapeBytea</function>,
    23542435
    and <function>PQnotifies</function>.
    @@ -4000,9 +4081,9 @@ current connection parameters will be used. (Therefore, put more-specific
    40004081
    entries first when you are using wildcards.)
    40014082
    If an entry needs to contain <literal>:</literal> or
    40024083
    <literal>\</literal>, escape this character with <literal>\</literal>.
    4003-
    A hostname of <literal>localhost</> matches both TCP <literal>host</> (hostname <literal>localhost</>)
    4004-
    and Unix domain socket <literal>local</> (<literal>pghost</> empty or the default socket directory)
    4005-
    connections coming from the local machine.
    4084+
    A hostname of <literal>localhost</> matches both TCP (hostname
    4085+
    <literal>localhost</>) and Unix domain socket (<literal>pghost</> empty or the
    4086+
    default socket directory) connections coming from the local machine.
    40064087
    </para>
    40074088

    40084089
    <para>

    ‎src/interfaces/libpq/exports.txt

    Lines changed: 4 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1,4 +1,4 @@
    1-
    # $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.7 2005/12/26 14:58:05 petere Exp $
    1+
    # $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.8 2006/05/21 20:19:23 tgl Exp $
    22
    # Functions to be exported by libpq DLLs
    33
    PQconnectdb 1
    44
    PQsetdbLogin 2
    @@ -125,4 +125,6 @@ PQcancel 122
    125125
    lo_create 123
    126126
    PQinitSSL 124
    127127
    PQregisterThreadLock 125
    128-
    PQencryptPassword 126
    128+
    PQescapeStringConn 126
    129+
    PQescapeByteaConn 127
    130+
    PQencryptPassword 128

    ‎src/interfaces/libpq/fe-connect.c

    Lines changed: 10 additions & 3 deletions
    Original file line numberDiff line numberDiff line change
    @@ -8,7 +8,7 @@
    88
    *
    99
    *
    1010
    * IDENTIFICATION
    11-
    * $PostgreSQL: pgsql/src/interfaces/libpq/fe-connect.c,v 1.331 2006/05/19 14:26:58 alvherre Exp $
    11+
    * $PostgreSQL: pgsql/src/interfaces/libpq/fe-connect.c,v 1.332 2006/05/21 20:19:23 tgl Exp $
    1212
    *
    1313
    *-------------------------------------------------------------------------
    1414
    */
    @@ -1828,6 +1828,7 @@ makeEmptyPGconn(void)
    18281828
    conn->nonblocking = false;
    18291829
    conn->setenv_state = SETENV_STATE_IDLE;
    18301830
    conn->client_encoding = PG_SQL_ASCII;
    1831+
    conn->std_strings = false; /* unless server says differently */
    18311832
    conn->verbosity = PQERRORS_DEFAULT;
    18321833
    conn->sock = -1;
    18331834
    #ifdef USE_SSL
    @@ -2944,8 +2945,14 @@ PQsetClientEncoding(PGconn *conn, const char *encoding)
    29442945
    status = -1;
    29452946
    else
    29462947
    {
    2947-
    /* change libpq internal encoding */
    2948-
    conn->client_encoding = pg_char_to_encoding(encoding);
    2948+
    /*
    2949+
    * In protocol 2 we have to assume the setting will stick, and
    2950+
    * adjust our state immediately. In protocol 3 and up we can
    2951+
    * rely on the backend to report the parameter value, and we'll
    2952+
    * change state at that time.
    2953+
    */
    2954+
    if (PG_PROTOCOL_MAJOR(conn->pversion) < 3)
    2955+
    pqSaveParameterStatus(conn, "client_encoding", encoding);
    29492956
    status = 0; /* everything is ok */
    29502957
    }
    29512958
    PQclear(res);

    0 commit comments

    Comments
     (0)
    0