</listitem>
</varlistentry>
+ <varlistentry>
+ <term><literal>scram-sha-256</literal></term>
+ <listitem>
+ <para>
+ Perform SCRAM-SHA-256 authentication to verify the user's password.
+ <note>
+ <para>
+ To use <literal>scram-sha-256</literal> authentication, you need to register
+ the user name and password in <filename>"pool_passwd"</filename>.
+ See <xref linkend="auth-scram"> for more details.
+ </para>
+ </note>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>cert</literal></term>
+ <listitem>
+ <para>
+ Authenticate using SSL client certificates.
+ See <xref linkend="auth-cert"> for more details.
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><literal>pam</literal></term>
<listitem>
<title>Authentication file format</title>
<para>
- This <literal>pool_passwd</literal> file should contain lines in the following format:
+ <literal>pool_passwd</literal> file should contain lines in the following format:
<programlisting>
"username:encrypted_passwd"
</programlisting>
</sect2>
+ <sect2 id="auth-scram">
+ <title>scram-sha-256 Authentication</title>
+
+ <indexterm zone="auth-scram">
+ <primary>SCRAM</primary>
+ </indexterm>
+
+ <para>
+ This authentication method also known as SCRAM is a
+ challenge-response based authentication that prevents the
+ password sniffing on untrusted connections.
+ Since <productname>Pgpool-II</productname> does not has the
+ visibility of <productname>PostgreSQL</productname>'s database user
+ password, so <literal>SCRAM</literal> authentication is supported using the
+ <xref linkend="guc-pool-passwd"> authentication file.
+ </para>
+
+ <sect3 id="scram-authentication-file-format">
+ <title>Authentication file entry for SCRAM</title>
+
+ <para>
+ To use the <literal>SCRAM</literal> authentication
+ <xref linkend="guc-pool-passwd"> authentication file
+ must contain the user password in either plain text
+ or <literal>AES</literal> encrypted format.
+
+ <programlisting>
+ "username:plain_text_passwd"
+ </programlisting>
+ <programlisting>
+ "username:AES_encrypted_passwd"
+ </programlisting>
+ <note>
+ <para>
+ <literal>md5</literal> type user passwords in
+ <xref linkend="guc-pool-passwd"> file can't be used for
+ <literal>scram</literal> authentication
+ </para>
+ </note>
+ </para>
+ </sect3>
+
+ <sect3 id="setting-scram-sha-256-authentication">
+ <title>Setting scram-sha-256 Authentication</title>
+ <indexterm zone="setting-scram-sha-256-authentication">
+ <primary>SCRAM</primary>
+ </indexterm>
+
+ <para>
+ Here are the steps to enable <literal>scram-sha-256</literal>
+ authentication:
+ </para>
+ <para>
+ 1- Create <xref linkend="guc-pool-passwd"> file entry
+ for database user and password in plain text or <literal>AES</literal>
+ encrypted format.
+ pg_enc ustility comes with <productname>Pgpool-II</productname>
+ can be used to create the <literal>AES</literal> encrypted password
+ entries in <xref linkend="guc-pool-passwd"> file.
+ <note>
+ <para>
+ User name and password must be identical to those registered
+ in <productname>PostgreSQL</productname> server.
+ </para>
+ </note>
+ </para>
+
+ <para>
+ 2- Add an appropriate scram-sha-256 entry to <filename>pool_hba.conf</filename>.
+ See <xref linkend="auth-pool-hba-conf"> for more details.
+ </para>
+ <para>
+ 3- After changing SCRAM password (in both pool_passwd
+ and <productname>PostgreSQL</productname> of course), reload
+ the pgpool configurations.
+ </para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="auth-cert">
+ <title>Certificate Authentication</title>
+
+ <indexterm zone="auth-cert">
+ <primary>Certificate</primary>
+ </indexterm>
+
+ <para>
+ This authentication method uses <literal>SSL</literal> client certificates
+ to perform authentication. It is therefore only available for SSL connections.
+ When using this authentication method, the <productname>Pgpool-II</productname>
+ will require that the client provide a valid certificate.
+ No password prompt will be sent to the client.
+ The <literal>cn</literal> (Common Name) attribute of the certificate will be
+ compared to the requested database user name, and if they match the login will
+ be allowed.
+ </para>
+
+ <note>
+ <para>
+ The certificate authentication works between client and
+ <productname>Pgpool-II</productname>, for the
+ backend authentication you can use any other authentication method
+ </para>
+ </note>
+
+ </sect2>
+
<sect2 id="auth-pam">
<title>PAM Authentication</title>
</sect2>
</sect1>
+ <sect1 id="auth-different-auth-method">
+ <title>Using different methods for frontend and backend authentication</title>
+
+ <indexterm zone="auth-different-auth-method">
+ <primary>AUTH</primary>
+ </indexterm>
+
+ <para>
+ Since <productname>Pgpool-II</productname><emphasis>V4.0</emphasis>
+ it possible to use different authentication for client application
+ and backend <productname>PostgreSQL</productname> servers.
+ For example, a client application can use <literal>scram-sha-256</literal>
+ to connect to <productname>Pgpool-II</productname> which
+ in turn can use <literal>trust</literal> or <literal>md5</literal>
+ authentication to connect to <productname>PostgreSQL</productname>
+ backend for the same session.
+
+ </para>
+ </sect1>
+
+ <sect1 id="auth-aes-encrypted-password">
+ <title>Using AES256 encrypted passwords in <filename>"pool_passwd"</filename> file</title>
+
+ <indexterm zone="auth-aes-encrypted-password">
+ <primary>AUTH</primary>
+ </indexterm>
+
+ <para>
+ Since the <literal>SCRAM</literal> authentication method explicitly
+ guards against the man-in-middle type attacks, so to use such authentication
+ methods <productname>Pgpool-II</productname> requires the
+ <productname>PostgreSQL</productname> user password to
+ authenticate with the backend.
+ </para>
+
+ <para>
+ But as storing the clear text password in the <filename>"pool_passwd"</filename>
+ file is never a good idea, so you can store the AES256 encrypted password
+ in the <filename>"pool_passwd"</filename>. To store the AES encrypted password
+ in the <filename>"pool_passwd"</filename> the password is first encrypted using
+ the AES256 encryption with the user provided key and then the encrypted password
+ is <literal>base64</literal> encoded and <literal>AES</literal> prefix is added
+ to the encoded string.
+ <note>
+ <para>
+ You can use the <command>pg_enc</command> utility to create the properly
+ formatted AES encrypted passwords.
+ </para>
+ </note>
+ </para>
+
+ <sect2 id="auth-create-aes-passwords">
+ <title>Creating encrypted password entries</title>
+ <para>
+ <command>pg_enc</command> can be used to create <literal>AES</literal>
+ encrypted password entries in <filename>"pool_passwd"</filename> file.
+ <command>pg_enc</command> requires the key for encrypting the password entries.
+ later that same key will be required by the <productname>Pgpool-II</productname>
+ to decrypt the passwords to use for authentication.
+ <note>
+ <para>
+ <productname>Pgpool-II</productname> must be build with ssl
+ (--with-openssl) support to use this encrypted password feature.
+ </para>
+ </note>
+ </para>
+ </sect2>
+
+ <sect2 id="auth-aes-decryption-key">
+ <title>Providing decryption key to <productname>Pgpool-II</productname></title>
+
+ <para>
+ If you have <literal>AES</literal> encrypted passwords stored in the
+ <filename>pool_passwd</filename> file, then <productname>Pgpool-II</productname>
+ will require the decryption key to decrypt the passwords before using them,
+ <productname>Pgpool-II</productname> tries to read the decryption key at
+ startup from the <filename>pgpoolkey</filename> file.
+ </para>
+ <para>
+ By default the <productname>Pgpool-II</productname> will look for the
+ <filename>pgpoolkey</filename> file in user's home directory or the file
+ referenced by environment variable <literal>PGPOOLKEYFILE</literal>.
+ You can also specify the key file using the (-k, --key-file=KEY_FILE)
+ command line argument to the <productname>Pgpool-II</productname> binary.
+ </para>
+ </sect2>
+
+ </sect1>
+
</chapter>
--- /dev/null
+<!--
+doc/src/sgml/ref/pg_enc.sgml
+Pgpool-II documentation
+-->
+
+<refentry id="PG-ENC">
+ <indexterm zone="pg-enc">
+ <primary>pg_enc</primary>
+ </indexterm>
+
+ <refmeta>
+ <refentrytitle>pg_enc</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo>Other Commands</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>pg_enc</refname>
+ <refpurpose>
+ password encryption utility
+ </refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>pg_enc</command>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
+ <arg choice="plain"><replaceable>-p</replaceable></arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>pg_enc</command>
+ <arg rep="repeat"><replaceable>option</replaceable></arg>
+ <arg choice="plain"><replaceable>password</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-PG-ENC-1">
+ <title>Description</title>
+ <para>
+ <command>pg_enc</command>
+ password encryption utility.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+ <para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-k <replaceable class="parameter">KEY_FILE</replaceable></option></term>
+ <term><option>--key-file=<replaceable class="parameter">KEY_FILE</replaceable></option></term>
+ <listitem>
+ <para>
+ Set the path to the encryption key file. Default is the <literal>.pgpoolkey</literal> file
+ located in the users home directory.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-K <replaceable class="parameter">ENCRYPTION_KEY</replaceable></option></term>
+ <term><option>--enc-key=<replaceable class="parameter">ENCRYPTION_KEY</replaceable></option></term>
+ <listitem>
+ <para>
+ Encryption key to be used for encrypting database passwords.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-f <replaceable class="parameter">CONFIG_FILE</replaceable></option></term>
+ <term><option>--config-file=<replaceable class="parameter">CONFIG_FILE</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the <literal>pgpool.conf</literal> file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-p</option></term>
+ <term><option>--prompt</option></term>
+ <listitem>
+ <para>
+ Prompt for database password using standard input.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-P</option></term>
+ <term><option>--prompt-for-key</option></term>
+ <listitem>
+ <para>
+ Prompt for encryption key using standard input.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-m</option></term>
+ <term><option>--update-pass</option></term>
+ <listitem>
+ <para>
+ Create encrypted password entry in the pool_passwd file.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-u <replaceable class="parameter">your_username</replaceable></option></term>
+ <term><option>--username=<replaceable class="parameter">your_username</replaceable></option></term>
+ <listitem>
+ <para>
+ Creates the <literal>pool_passwd</literal> entry for the database user called
+ <literal>your_username</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-h</option></term>
+ <term><option>--help</option></term>
+ <listitem>
+ <para>
+ Prints the help for <literal>pg_enc</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Example</title>
+ <para>
+ Here is an example output:
+ <programlisting>
+pg_enc -p
+db password: [your password]
+ </programlisting>
+ </para>
+ <para>
+ or
+ </para>
+ <programlisting>
+./pg_enc foo
+trying to read key from file /home/pgpool/.pgpoolkey
+
+jglid1QRgiCl/vfhHUDyVA==
+pool_passwd string: AESjglid1QRgiCl/vfhHUDyVA==
+ </programlisting>
+ <para>
+ <literal>pg_enc</literal> can be used for <literal>pool_passwd</literal> passwords with:
+ <programlisting>
+pg_enc -m -f /path/to/pgpool.conf -u username -p
+db password: [your password]
+ </programlisting>
+ which will add an entry for <literal>username</literal> with the password given.
+ </para>
+ </refsect1>
+
+</refentry>
if (pool_key == NULL)
{
- fprintf(stderr, "encryption key not provided");
+ fprintf(stderr, "encryption key not provided\n");
exit(EXIT_FAILURE);
}
}
if (pool_get_config(conf_file, CFGCXT_RELOAD) == false)
{
- fprintf(stderr, "Unable to get configuration. Exiting...");
+ fprintf(stderr, "Unable to get configuration. Exiting...\n\n");
exit(EXIT_FAILURE);
}
fprintf(stream, "Usage:\n");
fprintf(stream, " %s [OPTIONS] <PASSWORD>\n",prog);
fprintf(stream, " -k, --key-file=KEY_FILE\n");
- fprintf(stream, " Set the path to the encryption key file\n");
- fprintf(stream, " (default: %s/%s)\n",homedir, POOLKEYFILE);
- fprintf(stream, " can be over ridden by %s environment variable\n",POOLKEYFILEENV);
+ fprintf(stream, " Set the path to the encryption key file.\n");
+ fprintf(stream, " Default: %s/%s\n",homedir, POOLKEYFILE);
+ fprintf(stream, " Can be overridden by the %s environment variable.\n",POOLKEYFILEENV);
fprintf(stream, " -K, --enc-key=ENCRYPTION_KEY\n");
- fprintf(stream, " Encryption key to be used for encrypting database passwords\n");
- fprintf(stream, " Specify pgpool.conf\n");
+ fprintf(stream, " Encryption key to be used for encrypting database passwords.\n");
fprintf(stream, " -f, --config-file=CONFIG_FILE\n");
- fprintf(stream, " Encryption key to be used for encrypting database passwords\n");
+ fprintf(stream, " Specifies the pgpool.conf file.\n");
fprintf(stream, " -p, --prompt Prompt for database password using standard input.\n");
fprintf(stream, " -P, --prompt-for-key Prompt for encryption key using standard input.\n");
- fprintf(stream, " -m, --update-pass create encrypted password entry in pool_passwd file.\n");
- fprintf(stream, " -u, --username database USER for creating pool_password entry.\n");
- fprintf(stream, " -h, --help Print this help\n\n");
+ fprintf(stream, " -m, --update-pass Create encrypted password entry in the pool_passwd file.\n");
+ fprintf(stream, " -u, --username The username for the pool_password entry.\n");
+ fprintf(stream, " -h, --help Print this help.\n\n");
exit(exit_code);
}
projects / pgpool2.git / commitdiff