From ea9b028dc77e961b290087972b9bfbe8e91ce82f Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 23 Dec 2005 01:16:38 +0000
Subject: Add an officially exported libpq function to encrypt passwords, and
 modify the previous \password patch to use it instead of depending on a
 not-officially-exported function.  Per discussion.

---
 doc/src/sgml/libpq.sgml | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 5b0444190ca..df0ad527ae4 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.199 2005/11/04 23:14:00 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.200 2005/12/23 01:16:37 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -3565,6 +3565,40 @@ void PQuntrace(PGconn *conn);
 
 </sect1>
 
+<sect1 id="libpq-misc">
+<title>Miscellaneous Functions</title>
+
+<para>
+As always, there are some functions that just don't fit anywhere.
+</para>
+
+<variablelist>
+<varlistentry>
+<term><function>pg_make_encrypted_password</function><indexterm><primary>pg_make_encrypted_password</></></term>
+<listitem>
+<para>
+Prepares the encrypted form of a <productname>PostgreSQL</> password.
+<synopsis>
+char *pg_make_encrypted_password(const char *passwd, const char *user);
+</synopsis>
+<function>pg_make_encrypted_password</> is intended to be used by client
+applications that wish to send commands like
+<literal>ALTER USER joe PASSWORD 'pwd'</>.
+It is good practice not to send the original cleartext password in such a
+command, because it might be exposed in command logs, activity displays,
+and so on.  Instead, use this function to convert the password to encrypted
+form before it is sent.  The arguments are the cleartext password, and the SQL
+name of the user it is for.  The return value is a malloc'd string, or NULL if
+out-of-memory.  The caller may assume the string doesn't contain any weird
+characters that would require escaping.  Use <function>PQfreemem</> to free
+the result when done with it.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
 <sect1 id="libpq-notice-processing">
 <title>Notice Processing</title>
 
-- 
cgit v1.2.3