String escaping

Reveals "unescaped" version of PostgreSQL bytea string. More...

Functions

PGSTD::string PQXX_LIBEXPORT pqxx::escape_binary (const PGSTD::string &bin)
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::escape_binary (const char bin[])
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::escape_binary (const char bin[], size_t len)
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::escape_binary (const unsigned char bin[])
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::escape_binary (const unsigned char bin[], size_t len)
 Escape binary string for inclusion in SQL.
PGSTD::string pqxx::transaction_base::esc (const char str[]) const
 Escape string for use as SQL string literal in this transaction.
PGSTD::string pqxx::transaction_base::esc (const char str[], size_t maxlen) const
 Escape string for use as SQL string literal in this transaction.
PGSTD::string pqxx::transaction_base::esc (const PGSTD::string &) const
 Escape string for use as SQL string literal in this transaction.
PGSTD::string pqxx::transaction_base::esc_raw (const unsigned char str[], size_t len) const
 Escape binary data for use as SQL string literal in this transaction.
PGSTD::string pqxx::transaction_base::esc_raw (const PGSTD::string &) const
 Escape binary data for use as SQL string literal in this transaction.
PGSTD::string PQXX_LIBEXPORT pqxx::sqlesc (const char str[])
 Escape nul-terminated string for inclusion in SQL strings.
PGSTD::string PQXX_LIBEXPORT pqxx::sqlesc (const char str[], size_t maxlen)
 Escape string for inclusion in SQL strings.
PGSTD::string PQXX_LIBEXPORT pqxx::sqlesc (const PGSTD::string &)
 Escape string for inclusion in SQL strings.
template<typename T>
PGSTD::string pqxx::Quote (const T &Obj, bool EmptyIsNull) PQXX_DEPRECATED
 Quote string for use in SQL.
template<>
PGSTD::string pqxx::Quote (const PGSTD::string &Obj, bool EmptyIsNull) PQXX_DEPRECATED
 std::string version, on which the other versions are built
template<>
PGSTD::string pqxx::Quote (const char *const &Obj, bool EmptyIsNull) PQXX_DEPRECATED
 Special case for const char *, accepting null pointer as null value.
template<int LEN>
PGSTD::string pqxx::Quote (const char(&Obj)[LEN], bool EmptyIsNull) PQXX_DEPRECATED
 Specialization for string constants.
template<typename T>
PGSTD::string pqxx::Quote (T Obj) PQXX_DEPRECATED
 Quote string for use in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::binarystring::escape_binary (const PGSTD::string &bin)
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::binarystring::escape_binary (const char bin[])
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::binarystring::escape_binary (const char bin[], size_t len)
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::binarystring::escape_binary (const unsigned char bin[])
 Escape binary string for inclusion in SQL.
PGSTD::string PQXX_LIBEXPORT pqxx::binarystring::escape_binary (const unsigned char bin[], size_t len)
 Escape binary string for inclusion in SQL.

Detailed Description

Reveals "unescaped" version of PostgreSQL bytea string.

This class represents a postgres-internal buffer containing the original, binary string represented by a field of type bytea. The raw value returned by such a field contains escape sequences for certain characters, which are filtered out by binarystring.

The resulting string is zero-terminated, but may also contain zero bytes (or indeed any other byte value) so don't assume that it can be treated as a C-style string unless you've made sure of this yourself.

The binarystring retains its value even if the result it was obtained from is destroyed, but it cannot be copied or assigned.

To convert the other way, i.e. from a raw series of bytes to a string suitable for inclusion as bytea values in your SQL, use the transaction's esc_raw() functions.

Warning:
This class is implemented as a reference-counting smart pointer. Copying, swapping, and destroying binarystring objects that refer to the same underlying data block is not thread-safe. If you wish to pass binarystrings around between threads, make sure that each of these operations is protected against concurrency with similar operations on the same object, or other objects pointing to the same data block.
Use these functions to "groom" user-provided strings before using them in your SQL statements. This reduces the chance of unexpected failures when users type unexpected characters, but more importantly, it helps prevent so-called SQL injection attacks.

To understand what SQL injection vulnerabilities are and why they should be prevented, imagine you use the following SQL statement somewhere in your program:

        TX.exec("SELECT number,amount "
                "FROM accounts "
                "WHERE allowed_to_see('" + userid + "','" + password + "')");

This shows a logged-in user important information on all accounts he is authorized to view. The userid and password strings are variables entered by the user himself.

Now, if the user is actually an attacker who knows (or can guess) the general shape of this SQL statement, imagine he enters the following password:

        'x') OR ('x' = 'x

Does that make sense to you? Probably not. But if this is inserted into the SQL string by the C++ code above, the query becomes:

        SELECT number,amount
        FROM accounts
        WHERE allowed_to_see('user','x') OR ('x' = 'x')

Is this what you wanted to happen? Probably not! The neat allowed_to_see() clause is completely circumvented by the "<tt>OR ('x' = 'x')</tt>" clause, which is always true. Therefore, the attacker will get to see all accounts in the database!

To prevent this from happening, use the transaction's esc() function:

        TX.exec("SELECT number,amount "
                "FROM accounts "
                "WHERE allowed_to_see('" + TX.esc(userid) + "', "
                        "'" + TX.esc(password) + "')");

Now, the quotes embedded in the attacker's string will be neatly escaped so they can't "break out" of the quoted SQL string they were meant to go into:

        SELECT number,amount
        FROM accounts
        WHERE allowed_to_see('user', 'x'') OR (''x'' = ''x')

If you look carefully, you'll see that thanks to the added escape characters (a single-quote is escaped in SQL by doubling it) all we get is a very strange-looking password string--but not a change in the SQL statement.


Function Documentation

PGSTD::string pqxx::transaction_base::esc const PGSTD::string &   )  const [inherited]
 

Escape string for use as SQL string literal in this transaction.

PGSTD::string pqxx::transaction_base::esc const char  str[],
size_t  maxlen
const [inherited]
 

Escape string for use as SQL string literal in this transaction.

string pqxx::transaction_base::esc const char  str[]  )  const [inherited]
 

Escape string for use as SQL string literal in this transaction.

PGSTD::string pqxx::transaction_base::esc_raw const PGSTD::string &   )  const [inherited]
 

Escape binary data for use as SQL string literal in this transaction.

PGSTD::string pqxx::transaction_base::esc_raw const unsigned char  str[],
size_t  len
const [inherited]
 

Escape binary data for use as SQL string literal in this transaction.

Raw, binary data is treated differently from regular strings. Binary strings are never interpreted as text, so they may safely include byte values or byte sequences that don't happen to represent valid characters in the character encoding being used.

The binary string does not stop at the first zero byte, as is the case with textual strings. Instead, they may contain zero bytes anywhere. If it happens to contain bytes that look like quote characters, or other things that can disrupt their use in SQL queries, they will be replaced with special escape sequences.

PGSTD::string PQXX_LIBEXPORT escape_binary const unsigned char  bin[],
size_t  len
[related, inherited]
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const unsigned char  bin[]  )  [related, inherited]
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const char  bin[],
size_t  len
[related, inherited]
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const char  bin[]  )  [related, inherited]
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const PGSTD::string &  bin  )  [related, inherited]
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const unsigned char  bin[],
size_t  len
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const unsigned char  bin[]  ) 
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const char  bin[],
size_t  len
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const char  bin[]  ) 
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

PGSTD::string PQXX_LIBEXPORT escape_binary const PGSTD::string &  bin  ) 
 

Escape binary string for inclusion in SQL.

Deprecated:
Use the transaction's esc_raw() functions instead

template<typename T>
PGSTD::string pqxx::Quote Obj  ) 
 

Quote string for use in SQL.

This version of the function never generates null values.

Deprecated:
Use the transaction's esc() function instead

template<int LEN>
PGSTD::string pqxx::Quote const char &  Obj[LEN],
bool  EmptyIsNull
 

Specialization for string constants.

This specialization is a little complicated, because string constants are of the type char[], not of type const char * as one might expect. Note that the size of the array is part of the type, for which reason we need it in our template here.

Deprecated:
Use the transaction's esc() function instead

template<>
PGSTD::string pqxx::Quote const char *const &  Obj,
bool  EmptyIsNull
 

Special case for const char *, accepting null pointer as null value.

Deprecated:
Use the transaction's esc() function instead

template<>
PGSTD::string pqxx::Quote const PGSTD::string &  Obj,
bool  EmptyIsNull
 

std::string version, on which the other versions are built

Deprecated:
Use the transaction's esc() function instead

template<typename T>
PGSTD::string pqxx::Quote const T &  Obj,
bool  EmptyIsNull
 

Quote string for use in SQL.

Generate SQL-quoted version of string. If EmptyIsNull is set, an empty string will generate the null value rather than an empty string.

Deprecated:
Use the transaction's esc() function instead

PGSTD::string PQXX_LIBEXPORT pqxx::sqlesc const PGSTD::string &   ) 
 

Escape string for inclusion in SQL strings.

This works like the other sqlesc() variants, which means that if the string contains a nul character, conversion will stop there. PostgreSQL does not allow nul characters in strings.

Deprecated:
Use the transaction's esc() function instead

PGSTD::string PQXX_LIBEXPORT pqxx::sqlesc const char  str[],
size_t  maxlen
 

Escape string for inclusion in SQL strings.

Reads and escapes input string. The string is terminated by either a nul character or the given byte length, whichever comes first.

Parameters:
str optionally zero-terminated character string
maxlen largest possible length of input string, not including optional terminating nul character.
Unlike its predecessor Quote(), which is now obsolete, this function does not add SQL-style single quotes around the result string; nor does it recognize and generate nulls.

Deprecated:
Use the transaction's esc() function instead

PGSTD::string PQXX_LIBEXPORT pqxx::sqlesc const char  str[]  ) 
 

Escape nul-terminated string for inclusion in SQL strings.

Use this to sanitize strings that may contain characters like backslashes or quotes. You'll want to do this for all data received from outside your application that gets used in SQL--otherwise an attacker might crack your code by feeding it some string containing e.g. a closing quote followed by SQL commands you did not intend to execute.

Unlike its predecessor Quote(), which is now obsolete, this function does not add SQL-style single quotes around the result string; nor does it recognize and generate nulls.

Deprecated:
Use the transaction's esc() function instead


Generated on Sun Jun 18 15:06:08 2006 for libpqxx by  doxygen 1.4.6