String escaping

Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More...

## Functions

std::string | pqxx::escape_binary (const std::string &bin)
| Escape binary string for inclusion in SQL. More...
std::string | pqxx::escape_binary (const char bin[])
| Escape binary string for inclusion in SQL. More...
std::string | pqxx::escape_binary (const char bin[], size_t len)
| Escape binary string for inclusion in SQL. More...
std::string | pqxx::escape_binary (const unsigned char bin[])
| Escape binary string for inclusion in SQL. More...
std::string | pqxx::escape_binary (const unsigned char bin[], size_t len)
| Escape binary string for inclusion in SQL. More...
std::string | pqxx::connection_base::esc (const char str[])
| Escape string for use as SQL string literal on this connection. More...
std::string | pqxx::connection_base::esc (const char str[], size_t maxlen)
| Escape string for use as SQL string literal on this connection. More...
std::string | pqxx::connection_base::esc (const std::string &str)
| Escape string for use as SQL string literal on this connection. More...
std::string | pqxx::connection_base::esc_raw (const unsigned char str[], size_t len)
| Escape binary string for use as SQL string literal on this connection. More...
std::string | pqxx::connection_base::quote_raw (const unsigned char str[], size_t len)
| Escape and quote a string of binary data. More...
std::string | pqxx::connection_base::quote_name (const std::string &identifier)
| Escape and quote an SQL identifier for use in a query. More...
template<typename T >
std::string | pqxx::connection_base::quote (const T &t)
| Represent object as SQL string, including quoting & escaping. More...
std::string | pqxx::connection_base::quote (const binarystring &)
std::string | pqxx::transaction_base::esc (const char str[]) const
| Escape string for use as SQL string literal in this transaction. More...
std::string | pqxx::transaction_base::esc (const char str[], size_t maxlen) const
| Escape string for use as SQL string literal in this transaction. More...
std::string | pqxx::transaction_base::esc (const std::string &str) const
| Escape string for use as SQL string literal in this transaction. More...
std::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. More...
std::string | pqxx::transaction_base::esc_raw (const std::string &) const
| Escape binary data for use as SQL string literal in this transaction. More...
template<typename T >
std::string | pqxx::transaction_base::quote (const T &t) const
| Represent object as SQL string, including quoting & escaping. More...
std::string | pqxx::transaction_base::quote_raw (const unsigned char str[], size_t len) const
| Binary-escape and quote a binarystring for use as an SQL constant. More...
std::string | pqxx::transaction_base::quote_raw (const std::string &str) const
std::string | pqxx::transaction_base::quote_name (const std::string &identifier) const
| Escape an SQL identifier for use in a query. More...
std::string | escape_binary (const std::string &bin)
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const char bin[])
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const char bin[], size_t len)
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const unsigned char bin[])
| Escape binary string for inclusion in SQL. More...
std::string | escape_binary (const unsigned char bin[], size_t len)
| Escape binary string for inclusion in SQL. More...

## Detailed Description

Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.

This class represents a binary string as stored in a field of type bytea. The raw value returned by a bytea field contains escape sequences for certain characters, which are filtered out by binarystring.

Internally a binarystring is zero-terminated, but it may also contain zero bytes, just like 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 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

## esc() [1/6]

std::string pqxx::transaction_base::esc | ( | const char | str[] | ) | const

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

## esc() [2/6]

std::string pqxx::transaction_base::esc | ( | const char | str[],
|  | size_t | maxlen
| ) |  | const

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

## esc() [3/6]

std::string pqxx::transaction_base::esc | ( | const std::string & | str | ) | const

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

## esc() [4/6]

string pqxx::connection_base::esc | ( | const char | str[] | ) |

Escape string for use as SQL string literal on this connection.

Referenced by pqxx::connection_base::esc().

## esc() [5/6]

string pqxx::connection_base::esc | ( | const char | str[],
|  | size_t | maxlen
| ) |  |

Escape string for use as SQL string literal on this connection.

References pqxx::connection_base::activate().

## esc() [6/6]

string pqxx::connection_base::esc | ( | const std::string & | str | ) |

Escape string for use as SQL string literal on this connection.

References pqxx::connection_base::esc().

## esc_raw() [1/3]

std::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.

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.

## esc_raw() [2/3]

string pqxx::transaction_base::esc_raw | ( | const std::string & | str | ) | const

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

References pqxx::transaction_base::conn(), and pqxx::connection_base::esc_raw().

## esc_raw() [3/3]

string pqxx::connection_base::esc_raw | ( | const unsigned char | str[],
|  | size_t | len
| ) |  |

Escape binary string for use as SQL string literal on this connection.

References pqxx::connection_base::activate(), and pqxx::internal::PQAlloc< T, DELETER >::get().

Referenced by pqxx::transaction_base::esc_raw(), and pqxx::connection_base::quote_raw().

## escape_binary() [1/10]

std::string escape_binary | ( | const std::string & | bin | ) |

related

Escape binary string for inclusion in SQL.

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

Referenced by pqxx::escape_binary().

## escape_binary() [2/10]

string pqxx::escape_binary | ( | const std::string & | bin | ) |

Escape binary string for inclusion in SQL.

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

References pqxx::binarystring::escape_binary().

Referenced by pqxx::binarystring::get().

## escape_binary() [3/10]

string pqxx::escape_binary | ( | const char | bin[] | ) |

Escape binary string for inclusion in SQL.

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

References pqxx::binarystring::escape_binary().

## escape_binary() [4/10]

std::string escape_binary | ( | const char | bin[] | ) |

related

Escape binary string for inclusion in SQL.

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

## escape_binary() [5/10]

string pqxx::escape_binary | ( | const char | bin[],
|  | size_t | len
| ) |  |

Escape binary string for inclusion in SQL.

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

References pqxx::binarystring::escape_binary().

## escape_binary() [6/10]

std::string escape_binary | ( | const char | bin[],
|  | size_t | len
| ) |  |

related

Escape binary string for inclusion in SQL.

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

## escape_binary() [7/10]

string pqxx::escape_binary | ( | const unsigned char | bin[] | ) |

Escape binary string for inclusion in SQL.

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

References pqxx::binarystring::escape_binary().

## escape_binary() [8/10]

std::string escape_binary | ( | const unsigned char | bin[] | ) |

related

Escape binary string for inclusion in SQL.

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

## escape_binary() [9/10]

string pqxx::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

References pqxx::internal::PQAlloc< T, DELETER >::get().

## escape_binary() [10/10]

std::string escape_binary | ( | const unsigned char | bin[],
|  | size_t | len
| ) |  |

related

Escape binary string for inclusion in SQL.

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

## quote() [1/3]

template<typename T >

std::string pqxx::transaction_base::quote | ( | const T & | t | ) | const

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

Referenced by pqxx::basic_robusttransaction::~basic_robusttransaction().

## quote() [2/3]

template<typename T >

std::string pqxx::connection_base::quote | ( | const T & | t | ) |

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

References pqxx::to_string().

## quote() [3/3]

string pqxx::connection_base::quote | ( | const binarystring & | b | ) |

References pqxx::binarystring::data(), pqxx::connection_base::quote_raw(), and pqxx::binarystring::size().

## quote_name() [1/2]

std::string pqxx::transaction_base::quote_name | ( | const std::string & | identifier | ) | const

Escape an SQL identifier for use in a query.

## quote_name() [2/2]

string pqxx::connection_base::quote_name | ( | const std::string & | identifier | ) |

Escape and quote an SQL identifier for use in a query.

References pqxx::connection_base::activate(), pqxx::internal::PQAlloc< T, DELETER >::get(), and pqxx::internal::reactivation_avoidance_exemption::reactivation_avoidance_exemption().

## quote_raw() [1/3]

std::string pqxx::transaction_base::quote_raw | ( | const unsigned char | str[],
|  | size_t | len
| ) |  | const

Binary-escape and quote a binarystring for use as an SQL constant.

## quote_raw() [2/3]

string pqxx::transaction_base::quote_raw | ( | const std::string & | str | ) | const

References pqxx::transaction_base::Begin(), pqxx::transaction_base::conn(), pqxx::internal::namedclass::description(), and pqxx::connection_base::quote_raw().

## quote_raw() [3/3]

string pqxx::connection_base::quote_raw | ( | const unsigned char | str[],
|  | size_t | len
| ) |  |

Escape and quote a string of binary data.

References pqxx::connection_base::esc_raw().

Referenced by pqxx::connection_base::quote(), and pqxx::transaction_base::quote_raw().