From 7255b557fd14713574cf646718eacdaffb7328ed Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 18 Jan 2018 19:53:22 -0500 Subject: [PATCH 4/5] Move SSL API comments to header files Move the documentation of the SSL API calls are supposed to do into the headers files, instead of keeping them in the files for the OpenSSL implementation. That way, they don't have to be duplicated or be inconsistent when other implementations are added. --- src/backend/libpq/be-secure-openssl.c | 38 -------------------- src/include/libpq/libpq-be.h | 46 ++++++++++++++++++++++++ src/interfaces/libpq/fe-secure-openssl.c | 57 ++++------------------------- src/interfaces/libpq/libpq-int.h | 62 +++++++++++++++++++++++++++++++- 4 files changed, 113 insertions(+), 90 deletions(-) diff --git a/src/backend/libpq/be-secure-openssl.c b/src/backend/libpq/be-secure-openssl.c index 450a2f614c..f550ec82a9 100644 --- a/src/backend/libpq/be-secure-openssl.c +++ b/src/backend/libpq/be-secure-openssl.c @@ -70,13 +70,6 @@ static bool ssl_passwd_cb_called = false; /* Public interface */ /* ------------------------------------------------------------ */ -/* - * Initialize global SSL context. - * - * If isServerStart is true, report any errors as FATAL (so we don't return). - * Otherwise, log errors at LOG level and return -1 to indicate trouble, - * preserving the old SSL state if any. Returns 0 if OK. - */ int be_tls_init(bool isServerStart) { @@ -356,9 +349,6 @@ be_tls_init(bool isServerStart) return -1; } -/* - * Destroy global SSL context, if any. - */ void be_tls_destroy(void) { @@ -368,9 +358,6 @@ be_tls_destroy(void) ssl_loaded_verify_locations = false; } -/* - * Attempt to negotiate SSL connection. - */ int be_tls_open_server(Port *port) { @@ -539,9 +526,6 @@ be_tls_open_server(Port *port) return 0; } -/* - * Close SSL connection. - */ void be_tls_close(Port *port) { @@ -566,9 +550,6 @@ be_tls_close(Port *port) } } -/* - * Read data from a secure connection. - */ ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor) { @@ -628,9 +609,6 @@ be_tls_read(Port *port, void *ptr, size_t len, int *waitfor) return n; } -/* - * Write data to a secure connection. - */ ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor) { @@ -1106,9 +1084,6 @@ SSLerrmessage(unsigned long ecode) return errbuf; } -/* - * Return information about the SSL connection - */ int be_tls_get_cipher_bits(Port *port) { @@ -1159,12 +1134,6 @@ be_tls_get_peerdn_name(Port *port, char *ptr, size_t len) ptr[0] = '\0'; } -/* - * Routine to get the expected TLS Finished message information from the - * client, useful for authorization when doing channel binding. - * - * Result is a palloc'd copy of the TLS Finished message with its size. - */ char * be_tls_get_peer_finished(Port *port, size_t *len) { @@ -1183,13 +1152,6 @@ be_tls_get_peer_finished(Port *port, size_t *len) return result; } -/* - * Get the server certificate hash for SCRAM channel binding type - * tls-server-end-point. - * - * The result is a palloc'd hash of the server certificate with its - * size, and NULL if there is no certificate available. - */ char * be_tls_get_certificate_hash(Port *port, size_t *len) { diff --git a/src/include/libpq/libpq-be.h b/src/include/libpq/libpq-be.h index a38849b0d0..584f794b9e 100644 --- a/src/include/libpq/libpq-be.h +++ b/src/include/libpq/libpq-be.h @@ -216,19 +216,65 @@ CD1mpF1Bn5x8vYlLIhkmuquiXsNV6TILOwIBAg==\n\ * These functions are implemented by the glue code specific to each * SSL implementation (e.g. be-secure-openssl.c) */ + +/* + * Initialize global SSL context. + * + * If isServerStart is true, report any errors as FATAL (so we don't return). + * Otherwise, log errors at LOG level and return -1 to indicate trouble, + * preserving the old SSL state if any. Returns 0 if OK. + */ extern int be_tls_init(bool isServerStart); + +/* + * Destroy global SSL context, if any. + */ extern void be_tls_destroy(void); + +/* + * Attempt to negotiate SSL connection. + */ extern int be_tls_open_server(Port *port); + +/* + * Close SSL connection. + */ extern void be_tls_close(Port *port); + +/* + * Read data from a secure connection. + */ extern ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor); + +/* + * Write data to a secure connection. + */ extern ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor); +/* + * Return information about the SSL connection. + */ extern int be_tls_get_cipher_bits(Port *port); extern bool be_tls_get_compression(Port *port); extern void be_tls_get_version(Port *port, char *ptr, size_t len); extern void be_tls_get_cipher(Port *port, char *ptr, size_t len); extern void be_tls_get_peerdn_name(Port *port, char *ptr, size_t len); + +/* + * Get the expected TLS Finished message information from the client, useful + * for authorization when doing channel binding. + * + * Result is a palloc'd copy of the TLS Finished message with its size. + */ extern char *be_tls_get_peer_finished(Port *port, size_t *len); + +/* + * Get the server certificate hash for SCRAM channel binding type + * tls-server-end-point. + * + * The result is a palloc'd hash of the server certificate with its + * size, and NULL if there is no certificate available. + */ extern char *be_tls_get_certificate_hash(Port *port, size_t *len); #endif diff --git a/src/interfaces/libpq/fe-secure-openssl.c b/src/interfaces/libpq/fe-secure-openssl.c index b50bfd144a..eb13120941 100644 --- a/src/interfaces/libpq/fe-secure-openssl.c +++ b/src/interfaces/libpq/fe-secure-openssl.c @@ -98,10 +98,6 @@ static long win32_ssl_create_mutex = 0; /* Procedures common to all secure sessions */ /* ------------------------------------------------------------ */ -/* - * Exported function to allow application to tell us it's already - * initialized OpenSSL and/or libcrypto. - */ void pgtls_init_library(bool do_ssl, int do_crypto) { @@ -119,9 +115,6 @@ pgtls_init_library(bool do_ssl, int do_crypto) pq_init_crypto_lib = do_crypto; } -/* - * Begin or continue negotiating a secure session. - */ PostgresPollingStatusType pgtls_open_client(PGconn *conn) { @@ -144,22 +137,6 @@ pgtls_open_client(PGconn *conn) return open_client_SSL(conn); } -/* - * Is there unread data waiting in the SSL read buffer? - */ -bool -pgtls_read_pending(PGconn *conn) -{ - return SSL_pending(conn->ssl); -} - -/* - * Read data from a secure connection. - * - * On failure, this function is responsible for putting a suitable message - * into conn->errorMessage. The caller must still inspect errno, but only - * to determine whether to continue/retry after error. - */ ssize_t pgtls_read(PGconn *conn, void *ptr, size_t len) { @@ -284,13 +261,12 @@ pgtls_read(PGconn *conn, void *ptr, size_t len) return n; } -/* - * Write data to a secure connection. - * - * On failure, this function is responsible for putting a suitable message - * into conn->errorMessage. The caller must still inspect errno, but only - * to determine whether to continue/retry after error. - */ +bool +pgtls_read_pending(PGconn *conn) +{ + return SSL_pending(conn->ssl); +} + ssize_t pgtls_write(PGconn *conn, const void *ptr, size_t len) { @@ -393,12 +369,6 @@ pgtls_write(PGconn *conn, const void *ptr, size_t len) return n; } -/* - * Get the TLS finish message sent during last handshake - * - * This information is useful for callers doing channel binding during - * authentication. - */ char * pgtls_get_finished(PGconn *conn, size_t *len) { @@ -419,13 +389,6 @@ pgtls_get_finished(PGconn *conn, size_t *len) return result; } -/* - * Get the hash of the server certificate, for SCRAM channel binding type - * tls-server-end-point. - * - * NULL is sent back to the caller in the event of an error, with an - * error message for the caller to consume. - */ char * pgtls_get_peer_certificate_hash(PGconn *conn, size_t *len) { @@ -854,11 +817,6 @@ pq_lockingcallback(int mode, int n, const char *file, int line) * If the caller has told us (through PQinitOpenSSL) that he's taking care * of libcrypto, we expect that callbacks are already set, and won't try to * override it. - * - * The conn parameter is only used to be able to pass back an error - * message - no connection-local setup is made here. - * - * Returns 0 if OK, -1 on failure (with a message in conn->errorMessage). */ int pgtls_init(PGconn *conn) @@ -1493,9 +1451,6 @@ open_client_SSL(PGconn *conn) return PGRES_POLLING_OK; } -/* - * Close SSL connection. - */ void pgtls_close(PGconn *conn) { diff --git a/src/interfaces/libpq/libpq-int.h b/src/interfaces/libpq/libpq-int.h index 4e354098b3..b3492b033a 100644 --- a/src/interfaces/libpq/libpq-int.h +++ b/src/interfaces/libpq/libpq-int.h @@ -661,19 +661,79 @@ extern void pq_reset_sigpipe(sigset_t *osigset, bool sigpipe_pending, bool got_epipe); #endif +/* === SSL === */ + /* - * The SSL implementation provides these functions (fe-secure-openssl.c) + * The SSL implementation provides these functions. + */ + +/* + * Implementation of PQinitSSL(). */ extern void pgtls_init_library(bool do_ssl, int do_crypto); + +/* + * Initialize SSL library. + * + * The conn parameter is only used to be able to pass back an error + * message - no connection-local setup is made here. + * + * Returns 0 if OK, -1 on failure (with a message in conn->errorMessage). + */ extern int pgtls_init(PGconn *conn); + +/* + * Begin or continue negotiating a secure session. + */ extern PostgresPollingStatusType pgtls_open_client(PGconn *conn); + +/* + * Close SSL connection. + */ extern void pgtls_close(PGconn *conn); + +/* + * Read data from a secure connection. + * + * On failure, this function is responsible for putting a suitable message + * into conn->errorMessage. The caller must still inspect errno, but only + * to determine whether to continue/retry after error. + */ extern ssize_t pgtls_read(PGconn *conn, void *ptr, size_t len); + +/* + * Is there unread data waiting in the SSL read buffer? + */ extern bool pgtls_read_pending(PGconn *conn); + +/* + * Write data to a secure connection. + * + * On failure, this function is responsible for putting a suitable message + * into conn->errorMessage. The caller must still inspect errno, but only + * to determine whether to continue/retry after error. + */ extern ssize_t pgtls_write(PGconn *conn, const void *ptr, size_t len); + +/* + * Get the TLS finish message sent during last handshake. + * + * This information is useful for callers doing channel binding during + * authentication. + */ extern char *pgtls_get_finished(PGconn *conn, size_t *len); + +/* + * Get the hash of the server certificate, for SCRAM channel binding type + * tls-server-end-point. + * + * NULL is sent back to the caller in the event of an error, with an + * error message for the caller to consume. + */ extern char *pgtls_get_peer_certificate_hash(PGconn *conn, size_t *len); +/* === miscellaneous macros === */ + /* * this is so that we can check if a connection is non-blocking internally * without the overhead of a function call -- 2.15.1