diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 229e9d5a28..7dec1214c8 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,4 +1,4 @@ - + <application>libpq</application> - C Library @@ -2279,6 +2279,68 @@ in favor of PQescapeStringConn. + + Escaping Identifier for Inclusion in SQL Commands + + PQescapeIdentifier + escaping strings + + +PQescapeIdentifier escapes a string for use +as an identifier name within an SQL command. For example; table names, +column names, view names and user names are all identifiers. +Double quotes (") must be escaped to prevent them from being interpreted +specially by the SQL parser. PQescapeIdentifier performs this +operation. + + + + +It is especially important to do proper escaping when handling strings that +were received from an untrustworthy source. Otherwise there is a security +risk: you are vulnerable to SQL injection attacks wherein unwanted +SQL commands are fed to your database. + + + + +Note that it is still necessary to do escaping of identifiers when +using functions that support parameterized queries such as PQexecParams or +its sibling routines. Only literal values are automatically escaped +using these functions, not identifiers. + + +size_t PQescapeIdentifier (char *to, const char *from, size_t length); + + + + +The parameter from points to the first character of the +string that is to be escaped, and the length parameter +gives the number of characters in this string. A terminating zero byte +is not required, and should not be counted in length. (If +a terminating zero byte is found before length bytes are +processed, PQescapeIdentifier stops at the zero; the +behavior is thus rather like strncpy.) to +shall point to a buffer that is able to hold at least one more character +than twice the value of length, otherwise the behavior is +undefined. A call to PQescapeIdentifier writes an escaped +version of the from string to the to buffer, +replacing special characters so that they cannot cause any harm, and +adding a terminating zero byte. The double quotes that may surround +PostgreSQL identifiers are not included in the result +string; they should be provided in the SQL command that the result is +inserted into. + + +PQescapeIdentifier returns the number of characters written +to to, not including the terminating zero byte. + + +Behavior is undefined if the to and from +strings overlap. + + Escaping Binary Strings for Inclusion in SQL Commands diff --git a/src/interfaces/libpq/exports.txt b/src/interfaces/libpq/exports.txt index 84fe637c82..3765563843 100644 --- a/src/interfaces/libpq/exports.txt +++ b/src/interfaces/libpq/exports.txt @@ -1,4 +1,4 @@ -# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.11 2006/05/28 22:42:05 tgl Exp $ +# $PostgreSQL: pgsql/src/interfaces/libpq/exports.txt,v 1.12 2006/06/27 00:03:41 momjian Exp $ # Functions to be exported by libpq DLLs PQconnectdb 1 PQsetdbLogin 2 @@ -130,3 +130,5 @@ PQescapeByteaConn 127 PQencryptPassword 128 PQisthreadsafe 129 enlargePQExpBuffer 130 +PQescapeIdentifier 131 + diff --git a/src/interfaces/libpq/fe-exec.c b/src/interfaces/libpq/fe-exec.c index 69da7bc34c..76981fa0d1 100644 --- a/src/interfaces/libpq/fe-exec.c +++ b/src/interfaces/libpq/fe-exec.c @@ -8,7 +8,7 @@ * * * IDENTIFICATION - * $PostgreSQL: pgsql/src/interfaces/libpq/fe-exec.c,v 1.186 2006/05/28 21:13:54 tgl Exp $ + * $PostgreSQL: pgsql/src/interfaces/libpq/fe-exec.c,v 1.187 2006/06/27 00:03:41 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -2515,6 +2515,42 @@ PQescapeString(char *to, const char *from, size_t length) static_std_strings); } +/* + * Escaping arbitrary strings to get valid SQL identifier strings. + * + * Replaces " with "". + * + * length is the length of the source string. (Note: if a terminating NUL + * is encountered sooner, PQescapeIdentifier stops short of "length"; the behavior + * is thus rather like strncpy.) + * + * For safety the buffer at "to" must be at least 2*length + 1 bytes long. + * A terminating NUL character is added to the output string, whether the + * input is NUL-terminated or not. + * + * Returns the actual length of the output (not counting the terminating NUL). + */ +size_t +PQescapeIdentifier(char *to, const char *from, size_t length) +{ + const char *source = from; + char *target = to; + size_t remaining = length; + + while (remaining > 0 && *source != '\0') + { + if (*source == '"') + *target++ = *source; + *target++ = *source++; + remaining--; + } + + /* Write the terminating NUL character. */ + *target = '\0'; + + return target - to; +} + /* * PQescapeBytea - converts from binary string to the * minimal encoding necessary to include the string in an SQL diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h index 3b824efe85..272ccc87de 100644 --- a/src/interfaces/libpq/libpq-fe.h +++ b/src/interfaces/libpq/libpq-fe.h @@ -7,7 +7,7 @@ * Portions Copyright (c) 1996-2006, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * - * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.129 2006/05/23 22:13:19 momjian Exp $ + * $PostgreSQL: pgsql/src/interfaces/libpq/libpq-fe.h,v 1.130 2006/06/27 00:03:42 momjian Exp $ * *------------------------------------------------------------------------- */ @@ -436,6 +436,8 @@ extern unsigned char *PQescapeByteaConn(PGconn *conn, size_t *to_length); extern unsigned char *PQunescapeBytea(const unsigned char *strtext, size_t *retbuflen); +extern size_t PQescapeIdentifier(char *to, const char *from, size_t length); + /* These forms are deprecated! */ extern size_t PQescapeString(char *to, const char *from, size_t length); extern unsigned char *PQescapeBytea(const unsigned char *from, size_t from_length,