From: Muhammad Usama Date: Wed, 15 Aug 2018 22:04:25 +0000 (+0500) Subject: Documentation for SCRAM and CERT authentication feature. X-Git-Url: http://git.postgresql.org/gitweb/static/gitweb.js?a=commitdiff_plain;h=539ca526e635fdd5a563074c48abeef918371b4b;p=pgpool2.git Documentation for SCRAM and CERT authentication feature. pg_enc documentation contributed by jesperpedersen --- diff --git a/doc/src/sgml/client-auth.sgml b/doc/src/sgml/client-auth.sgml index 7fe6f7978..3ed7bdc34 100644 --- a/doc/src/sgml/client-auth.sgml +++ b/doc/src/sgml/client-auth.sgml @@ -360,6 +360,32 @@ + + scram-sha-256 + + + Perform SCRAM-SHA-256 authentication to verify the user's password. + + + To use scram-sha-256 authentication, you need to register + the user name and password in "pool_passwd". + See for more details. + + + + + + + + cert + + + Authenticate using SSL client certificates. + See for more details. + + + + pam @@ -517,7 +543,7 @@ Authentication file format - This pool_passwd file should contain lines in the following format: + pool_passwd file should contain lines in the following format: "username:encrypted_passwd" @@ -561,6 +587,114 @@ + + scram-sha-256 Authentication + + + SCRAM + + + + This authentication method also known as SCRAM is a + challenge-response based authentication that prevents the + password sniffing on untrusted connections. + Since Pgpool-II does not has the + visibility of PostgreSQL's database user + password, so SCRAM authentication is supported using the + authentication file. + + + + Authentication file entry for SCRAM + + + To use the SCRAM authentication + authentication file + must contain the user password in either plain text + or AES encrypted format. + + + "username:plain_text_passwd" + + + "username:AES_encrypted_passwd" + + + + md5 type user passwords in + file can't be used for + scram authentication + + + + + + + Setting scram-sha-256 Authentication + + SCRAM + + + + Here are the steps to enable scram-sha-256 + authentication: + + + 1- Create file entry + for database user and password in plain text or AES + encrypted format. + pg_enc ustility comes with Pgpool-II + can be used to create the AES encrypted password + entries in file. + + + User name and password must be identical to those registered + in PostgreSQL server. + + + + + + 2- Add an appropriate scram-sha-256 entry to pool_hba.conf. + See for more details. + + + 3- After changing SCRAM password (in both pool_passwd + and PostgreSQL of course), reload + the pgpool configurations. + + + + + + + Certificate Authentication + + + Certificate + + + + This authentication method uses SSL client certificates + to perform authentication. It is therefore only available for SSL connections. + When using this authentication method, the Pgpool-II + will require that the client provide a valid certificate. + No password prompt will be sent to the client. + The cn (Common Name) attribute of the certificate will be + compared to the requested database user name, and if they match the login will + be allowed. + + + + + The certificate authentication works between client and + Pgpool-II, for the + backend authentication you can use any other authentication method + + + + + PAM Authentication @@ -597,4 +731,93 @@ + + Using different methods for frontend and backend authentication + + + AUTH + + + + Since Pgpool-IIV4.0 + it possible to use different authentication for client application + and backend PostgreSQL servers. + For example, a client application can use scram-sha-256 + to connect to Pgpool-II which + in turn can use trust or md5 + authentication to connect to PostgreSQL + backend for the same session. + + + + + + Using AES256 encrypted passwords in <filename>"pool_passwd"</filename> file + + + AUTH + + + + Since the SCRAM authentication method explicitly + guards against the man-in-middle type attacks, so to use such authentication + methods Pgpool-II requires the + PostgreSQL user password to + authenticate with the backend. + + + + But as storing the clear text password in the "pool_passwd" + file is never a good idea, so you can store the AES256 encrypted password + in the "pool_passwd". To store the AES encrypted password + in the "pool_passwd" the password is first encrypted using + the AES256 encryption with the user provided key and then the encrypted password + is base64 encoded and AES prefix is added + to the encoded string. + + + You can use the pg_enc utility to create the properly + formatted AES encrypted passwords. + + + + + + Creating encrypted password entries + + pg_enc can be used to create AES + encrypted password entries in "pool_passwd" file. + pg_enc requires the key for encrypting the password entries. + later that same key will be required by the Pgpool-II + to decrypt the passwords to use for authentication. + + + Pgpool-II must be build with ssl + (--with-openssl) support to use this encrypted password feature. + + + + + + + Providing decryption key to <productname>Pgpool-II</productname> + + + If you have AES encrypted passwords stored in the + pool_passwd file, then Pgpool-II + will require the decryption key to decrypt the passwords before using them, + Pgpool-II tries to read the decryption key at + startup from the pgpoolkey file. + + + By default the Pgpool-II will look for the + pgpoolkey file in user's home directory or the file + referenced by environment variable PGPOOLKEYFILE. + You can also specify the key file using the (-k, --key-file=KEY_FILE) + command line argument to the Pgpool-II binary. + + + + + diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index d20fde677..27ec7d068 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -17,6 +17,7 @@ Complete list of usable sgml source files in this directory. + diff --git a/doc/src/sgml/ref/pg_enc.sgml b/doc/src/sgml/ref/pg_enc.sgml new file mode 100644 index 000000000..77e6f746b --- /dev/null +++ b/doc/src/sgml/ref/pg_enc.sgml @@ -0,0 +1,165 @@ + + + + + pg_enc + + + + pg_enc + 1 + Other Commands + + + + pg_enc + + password encryption utility + + + + + + pg_enc + option + -p + + + pg_enc + option + password + + + + + Description + + pg_enc + password encryption utility. + + + + + Options + + + + + + + + + Set the path to the encryption key file. Default is the .pgpoolkey file + located in the users home directory. + + + + + + + + + + Encryption key to be used for encrypting database passwords. + + + + + + + + + + Specifies the pgpool.conf file. + + + + + + + + + + Prompt for database password using standard input. + + + + + + + + + + Prompt for encryption key using standard input. + + + + + + + + + + Create encrypted password entry in the pool_passwd file. + + + + + + + + + + Creates the pool_passwd entry for the database user called + your_username. + + + + + + + + + + Prints the help for pg_enc. + + + + + + + + + + Example + + Here is an example output: + +pg_enc -p +db password: [your password] + + + + or + + +./pg_enc foo +trying to read key from file /home/pgpool/.pgpoolkey + +jglid1QRgiCl/vfhHUDyVA== +pool_passwd string: AESjglid1QRgiCl/vfhHUDyVA== + + + pg_enc can be used for pool_passwd passwords with: + +pg_enc -m -f /path/to/pgpool.conf -u username -p +db password: [your password] + + which will add an entry for username with the password given. + + + + diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index a53149aa5..e9c101441 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -113,6 +113,7 @@ &pgMd5; + &pgEnc; &pgpoolSetup; &watchdoglSetup; diff --git a/src/tools/pgenc/pg_enc.c b/src/tools/pgenc/pg_enc.c index 8671b4490..604c622ec 100644 --- a/src/tools/pgenc/pg_enc.c +++ b/src/tools/pgenc/pg_enc.c @@ -249,7 +249,7 @@ main(int argc, char *argv[]) if (pool_key == NULL) { - fprintf(stderr, "encryption key not provided"); + fprintf(stderr, "encryption key not provided\n"); exit(EXIT_FAILURE); } @@ -308,7 +308,7 @@ static void update_pool_passwd(char *conf_file, char *username, char *password, } 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); } @@ -366,19 +366,18 @@ print_usage(const char prog[], int exit_code) fprintf(stream, "Usage:\n"); fprintf(stream, " %s [OPTIONS] \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); }