From 3b1790f9875e0221d6ae305a596f506647fa2554 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Tue, 27 Jun 2006 00:03:42 +0000
Subject: [PATCH] Add PQescapeIdentifier() to libpq
Christopher Kings-Lynne
---
doc/src/sgml/libpq.sgml | 64 +++++++++++++++++++++++++++++++-
src/interfaces/libpq/exports.txt | 4 +-
src/interfaces/libpq/fe-exec.c | 38 ++++++++++++++++++-
src/interfaces/libpq/libpq-fe.h | 4 +-
4 files changed, 106 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 229e9d5a28f..7dec1214c83 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.211 2006/05/23 22:13:19 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.212 2006/06/27 00:03:41 momjian Exp $ -->
<chapter id="libpq">
<title><application>libpq</application> - C Library</title>
@@ -2279,6 +2279,68 @@ in favor of <function>PQescapeStringConn</>.
</para>
</sect2>
+<sect2 id="libpq-exec-escape-identifier">
+ <title>Escaping Identifier for Inclusion in SQL Commands</title>
+
+ <indexterm zone="libpq-exec-escape-identifier"><primary>PQescapeIdentifier</></>
+ <indexterm zone="libpq-exec-escape-identifier"><primary>escaping strings</></>
+
+<para>
+<function>PQescapeIdentifier</function> 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. <function>PQescapeIdentifier</> performs this
+operation.
+</para>
+
+<tip>
+<para>
+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 <quote>SQL injection</> attacks wherein unwanted
+SQL commands are fed to your database.
+</para>
+</tip>
+
+<para>
+Note that it is still necessary to do escaping of identifiers when
+using functions that support parameterized queries such as <function>PQexecParams</> or
+its sibling routines. Only literal values are automatically escaped
+using these functions, not identifiers.
+
+<synopsis>
+size_t PQescapeIdentifier (char *to, const char *from, size_t length);
+</synopsis>
+</para>
+
+<para>
+The parameter <parameter>from</> points to the first character of the
+string that is to be escaped, and the <parameter>length</> parameter
+gives the number of characters in this string. A terminating zero byte
+is not required, and should not be counted in <parameter>length</>. (If
+a terminating zero byte is found before <parameter>length</> bytes are
+processed, <function>PQescapeIdentifier</> stops at the zero; the
+behavior is thus rather like <function>strncpy</>.) <parameter>to</>
+shall point to a buffer that is able to hold at least one more character
+than twice the value of <parameter>length</>, otherwise the behavior is
+undefined. A call to <function>PQescapeIdentifier</> writes an escaped
+version of the <parameter>from</> string to the <parameter>to</> buffer,
+replacing special characters so that they cannot cause any harm, and
+adding a terminating zero byte. The double quotes that may surround
+<productname>PostgreSQL</> identifiers are not included in the result
+string; they should be provided in the SQL command that the result is
+inserted into.
+</para>
+<para>
+<function>PQescapeIdentifier</> returns the number of characters written
+to <parameter>to</>, not including the terminating zero byte.
+</para>
+<para>
+Behavior is undefined if the <parameter>to</> and <parameter>from</>
+strings overlap.
+</para>
+</sect2>
<sect2 id="libpq-exec-escape-bytea">
<title>Escaping Binary Strings for Inclusion in SQL Commands</title>
diff --git a/src/interfaces/libpq/exports.txt b/src/interfaces/libpq/exports.txt
index 84fe637c82b..37655638434 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 69da7bc34c5..76981fa0d1e 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 3b824efe852..272ccc87deb 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,
--
GitLab