From 7441f6c7b0af2e740147b9e7617a445c7e24a15e Mon Sep 17 00:00:00 2001 From: Guillaume Hivert Date: Tue, 19 Nov 2024 17:36:51 +0100 Subject: [PATCH] Improve SSL documentation --- README.md | 185 ++++++++++++++----------------------- docs/solving-ssl-issues.md | 128 +++++++++++++++++++++++++ gleam.toml | 5 + src/pog.gleam | 16 +++- src/pog_ffi.erl | 4 +- 5 files changed, 213 insertions(+), 125 deletions(-) create mode 100644 docs/solving-ssl-issues.md diff --git a/README.md b/README.md index b4019d0..0e33155 100644 --- a/README.md +++ b/README.md @@ -120,125 +120,74 @@ the VM crashing. Due to this limitation you should not dynamically open new connection pools, instead create the pools you need when your application starts and reuse them throughout the lifetime of your program. +## SSL + +As for the rest of the web, you should try to use SSL connections with any +Postgres database. Most of the time, managed instances of Postgres will even +require the library to use SSL connections. + +`pog` supports SSL connections out-of-the-box, and stick with current Postgres +conventions to ensure portability of Postgres configuration across ecosystems. + +### Postgres SSL conventions + +Postgres supports 3 main modes of SSL: SSL disabled, SSL enabled, and SSL +enabled with active security measures (i.e. checking of system-wide CA +certificates). Those modes can be found directly in `psql` client, but also in +most Postgres clients in different languages. + +> [!NOTE] +> It could seems weird to have three different modes of SSL, while we usually +> think of SSL a switch: it's turned off, or turned on. When SSL is off, clients +> will simply ignore SSL certificates, and proceed with the connection in an +> unsecured way (as long as the server agrees with unsecure connection). When +> SSL is on, clients will read SSL certificates, and check that the connection +> uses a correct SSL certificates. It will read global Certificates Authority +> and will check that your connection is secured with one of those certificates. +> If we take the browser analogy, SSL turned off is when you're browsing an HTTP +> website, while SSL turned on is when you're browsing an HTTPS website. +> But there's a hidden mode of SSL, where SSL is enabled, but not actively +> checking that the connection is valid. In simple terms, it means the connection +> can be compromised, and the client will not check for Certificates Authority. +> You'll use the SSL connection thinking you are secured, but some potential +> attackers can target you. Continuing the browser analogy, it's when you are +> on a website secured by HTTPS, but the browser will show a warning page saying +> "Impossible to check the validity of certificate.", and you have to click on +> "Continue anyway". When you click on that button, you're using that third mode +> of SSL: it's secured, but you can not be certain that the connection is legit! + +In Postgres, conventions used, including in connection URI are as follow: + +- Flag used to indicate SSL state is named `sslmode`. +- `disable` disables SSL connection. +- `require` enables SSL connection, but does not check CA certificates. +- `verify-ca` or `verify-full` enables SSL connection, and check for CA certificates. + +### `pog` SSL usage + +In `pog`, setting up an SSL connection simply ask you to indicate the proper flag +in `pog.Config`. The different options are `SslDisabled`, `SslUnsafe` & +`SslEnabled`. Because of the nature of the 3 modes of SSL, and because talking +to your database should be highly secured to protect you against man-in-the-middle +attacks, you should always try to use the most secured setting. + +```gleam +import pog + +pub fn connect() { + pog.default_config() + |> pog.ssl(pog.SslSecured) + |> pog.connect +} +``` + +### Need some help? + +You tried to setup a secured connection, but it does not work? Your container +is not able to find the correct CA certificate? +[Take a look at Solving SSL issues](https://hexdocs.pm/pog/docs/solving-ssl-issues.html) + ## History Previously this library was named `gleam_pgo`. This old name is deprecated and all future development and support will happen here. - -## SSL options and CA Certificates - -`gleam_pgo` supports two main modes of SSL: `SslEnabled` and `SslVerify`. The -latter is the most secured form of SSL, checking every signatures against the -system-wide CA certificates provided by the OS. - -You can easily enable one or the other using `ssl: SslEnabled` or -`ssl: SslDisabled` in `pgo.Config`. `sslmode` is also supported in configuration -URI. The different values allowed are `disable`, `require`, `verify-ca` and -`verify-full` (as specified in Postgres documentation). - -Below a little bit more explanations on SSL if you need to understand better -what's happening, and some common problems. - -### A word on SSL connections - -Every SSL connection should be setup using an SSL certificate. An SSL certificate -is notably made of a signature of a Certificate Authority (CA), and a public key. -Those two parts allow to establish the secured connection as well as checking -the validity of the certificate. When opening a connection with a server secured -with SSL, the server will send the certificate, and every data will be -subsequently sent encrypted with a private key that can be decrypted using the -public key of the certificate. However, we cannot trust a certificate, because an -attacker can create a certificate on its own. That's where the signature comes into -play: the signature of the CA cannot be easily compromised. When a client -receives an SSL certificate, it will first check the CA signature against a list -of known authorities, and if one of them match, it means the SSL certificate -can be trusted. - -### What does it mean for Postgres? - -Therefore, it's possible to use an SSL connection with different modes: -accepting SSL, but skipping verification of CA certificate, and accepting -SSL _and_ verifying CA certificate. Most of the time and when in critical -environment, you should _always_ verify the CA certificate. However, some -situations can ask to disable that layer of security, mainly because of -self-issued certificates. - -One common situation is when using a managed version of Postgres, for instance -on Digital Ocean or AWS RDS. Those managed services are powerful hosted services -of Postgres, but to avoid spending money on SSL certificates, they prefer issue -their own certificates. It means they created a custom CA certificate, and they -issue SSL certificates for databases with that custom CA certificate. Because -that certificate is not in your default environment, setting a connection with -`SslVerify` _will_ fail, because BEAM will not be able to check the validity of -the certificate. All it will be able to do is guaranteeing the connection is -encrypted with SSL. Switching to `SslEnabled` can suffice, especially if your -instance is secured in your VPC. However, you're still a potential target for a -man-in-the-middle attack. - -### Solving the CA certificate issue - -To solve the custom CA certificate problem, what is needed is to provide the CA -certificate itself, to check the SSL certificate of the database against it. -`gleam_pgo` tries to solve the problem in an elegant way. Instead of having to -grab the certificate and handle it in your application code, `gleam_pgo` will -read the certificates from your OS, using Erlang function -`public_key:cacerts_get()`. - -#### Adding the custom CA certificate in your OS certificate chain - -Adding the CA certificate depends on your OS: - -##### Linux - -CA certificates are managed through the `ca-certificates` package. -Every common installation of Linux have it already installed, excepted Alpine. -Once the package is installed, you should get the certificates you want to add -in `.pem` format to the system, and put it in `/usr/local/share/ca-certificates`, -with a `.crt` extension. Run `update-ca-certificates` and voilà! Your -certificate is added in the certificate chain! - -Be careful though, a PEM file can contains _multiple_ certificates. In that case, -you can simply split the PEM file in multiple CRT files, -[like suggested on ServerFault](https://serverfault.com/questions/391396/how-to-split-a-pem-file), -or you could simply push all certificates in the certificate chain by hand! All -`update-ca-certificates` will do is concatenating certificates in -`/etc/ssl/certs/ca-certificates.crt`. A simple `cat my-certificates.pem >> /etc/ssl/certs/ca-certificates.crt` will do the trick! Be careful though, everytime the OS will -run `update-ca-certificates` by itself, you'll have to redo the operation. In such -cases, it's recommended to add the certificates in `/usr/local/share/ca-certificates`, -but it could be useful in case you building a Docker image for example! - -##### macOS - -CA certificates can simply be added on the system using the keychain! Double-click -on the certificates, and let macOS work for you! - -##### \[Reminder\] Shape of a PEM certificate - -A PEM certificate looks like this: (example taken from an AWS `eu-west-1` certificate) - -``` ------BEGIN CERTIFICATE----- -MIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD -VQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi -MCAGA1UECgwZQW1hem9uIFdlYiBTZXJ2aWNlcywgSW5jLjETMBEGA1UECwwKQW1h -em9uIFJEUzEgMB4GA1UEAwwXQW1hem9uIFJEUyBSb290IDIwMTkgQ0EwHhcNMTkw -ODIyMTcwODUwWhcNMjQwODIyMTcwODUwWjCBjzELMAkGA1UEBhMCVVMxEDAOBgNV -BAcMB1NlYXR0bGUxEzARBgNVBAgMCldhc2hpbmd0b24xIjAgBgNVBAoMGUFtYXpv -biBXZWIgU2VydmljZXMsIEluYy4xEzARBgNVBAsMCkFtYXpvbiBSRFMxIDAeBgNV -BAMMF0FtYXpvbiBSRFMgUm9vdCAyMDE5IENBMIIBIjANBgkqhkiG9w0BAQEFAAOC -AQ8AMIIBCgKCAQEArXnF/E6/Qh+ku3hQTSKPMhQQlCpoWvnIthzX6MK3p5a0eXKZ -oWIjYcNNG6UwJjp4fUXl6glp53Jobn+tWNX88dNH2n8DVbppSwScVE2LpuL+94vY -0EYE/XxN7svKea8YvlrqkUBKyxLxTjh+U/KrGOaHxz9v0l6ZNlDbuaZw3qIWdD/I -6aNbGeRUVtpM6P+bWIoxVl/caQylQS6CEYUk+CpVyJSkopwJlzXT07tMoDL5WgX9 -O08KVgDNz9qP/IGtAcRduRcNioH3E9v981QO1zt/Gpb2f8NqAjUUCUZzOnij6mx9 -McZ+9cWX88CRzR0vQODWuZscgI08NvM69Fn2SQIDAQABo2MwYTAOBgNVHQ8BAf8E -BAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUc19g2LzLA5j0Kxc0LjZa -pmD/vB8wHwYDVR0jBBgwFoAUc19g2LzLA5j0Kxc0LjZapmD/vB8wDQYJKoZIhvcN -AQELBQADggEBAHAG7WTmyjzPRIM85rVj+fWHsLIvqpw6DObIjMWokpliCeMINZFV -ynfgBKsf1ExwbvJNzYFXW6dihnguDG9VMPpi2up/ctQTN8tm9nDKOy08uNZoofMc -NUZxKCEkVKZv+IL4oHoeayt8egtv3ujJM6V14AstMQ6SwvwvA93EP/Ug2e4WAXHu -cbI1NAbUgVDqp+DRdfvZkgYKryjTWd/0+1fS8X1bBZVWzl7eirNVnHbSH2ZDpNuY -0SBd8dj5F6ld3t58ydZbrTHze7JJOd8ijySAp4/kiu9UfZWuTPABzDa/DSdz9Dk/ -zPW4CXXvhLmE02TA9/HeCw3KEHIwicNuEfw= ------END CERTIFICATE----- -``` diff --git a/docs/solving-ssl-issues.md b/docs/solving-ssl-issues.md new file mode 100644 index 0000000..c8673f4 --- /dev/null +++ b/docs/solving-ssl-issues.md @@ -0,0 +1,128 @@ +# Solving SSL issues + +Talking to your database should always be secured (if possible), because it's one +of the most sensible operation in your daily production setup. As such, a lot of +Postgres databases are secured through SSL. Most of the time, managed instances of +Postgres require you to use an SSL connection. But finding the correct SSL setup +can be hard, because it ask you to have some knowledge on how SSL and your OS +works under-the-hood. + +That guide is here to help you setup correctly your database connection. + +## Understanding SSL/TLS connections + +An SSL/TLS connection is different from a plain connection by its nature: when with +plain connections, you just send the bits on the wire in a public way (so anybody +can see what bits transit in the network), SSL/TLS connections encrypt every bits +between you and the server. It means nobody can see what you're exchanging with +the server. Of course, this is a requirement when you're dealing with sensible +data (password, health data, etc.), but it's also becoming the standard when +browsing the web those days. + +SSL/TLS connections rely on [asymmetric encryption](https://en.wikipedia.org/wiki/Public-key_cryptography). +When you're talking to a secured server, your client will ask for the public SSL +certificate, containing the public key, and will try to see if it has been issued by +a well-known, certified authority. If everything went well, the client can continue, +and will generate some session keys to talk with the server. After that process, +your connection will be 100% encrypted, and impossible to understand for the rest +of the world. + +### Solving the CA certificate OS issue + +However, sometimes, CA certificates can be missing. While OS maintains a list of +CA certificates to simplify the life of every users, the CA certificate used by +your server can be a _self signed certificate_ for example. It means, even if +it's properly secured, everyone will have an error, rejecting because the CA +certificate can not be verified. + +To make sure your error comes from an CA certificate issue, it's recommended to +first test your connection in `pog` with `ssl: pog.SslUnsafe`. Because of the +nature of the setting, if the only error comes from SSL, it should work directly. +If it does not work, your problem comes from something else. + +In such case, it's required to provide the correct CA certificates to the client. +`pog` tries to solve the problem in an elegant way. Instead of having to +grab the certificate and handle it in your application code, `pog` will +read the certificates from your OS, using Erlang function +`public_key:cacerts_get()`. + +#### Adding the custom CA certificate in your OS certificate chain + +Adding the CA certificate depends on your OS: + +##### Linux + +CA certificates are managed through the `ca-certificates` package. +Every common installation of Linux have it already installed, excepted Alpine. +Once the package is installed, you should get the certificates you want to add +in `.pem` format to the system, and put it in `/usr/local/share/ca-certificates`, +with a `.crt` extension. Run `update-ca-certificates` and voilà! Your +certificate is added in the certificate chain! + +Be careful though, a PEM file can contains _multiple_ certificates. In that case, +you can simply split the PEM file in multiple CRT files, +[like suggested on ServerFault](https://serverfault.com/questions/391396/how-to-split-a-pem-file), +or you could simply push all certificates in the certificate chain by hand! All +`update-ca-certificates` will do is concatenating certificates in +`/etc/ssl/certs/ca-certificates.crt`. A simple `cat my-certificates.pem >> /etc/ssl/certs/ca-certificates.crt` +will do the trick! Be careful though, everytime the OS will +run `update-ca-certificates` by itself, you'll have to redo the operation. In such +cases, it's recommended to add the certificates in `/usr/local/share/ca-certificates`, +but it could be useful in case you're building a Docker image for example! + +##### macOS + +CA certificates can simply be added on the system using the keychain! Double-click +on the certificates, and let macOS work for you! + +##### \[Reminder\] Shape of a PEM certificate + +A PEM certificate looks like this: (example taken from an AWS `eu-west-1` certificate) + +``` +-----BEGIN CERTIFICATE----- +MIIEBjCCAu6gAwIBAgIJAMc0ZzaSUK51MA0GCSqGSIb3DQEBCwUAMIGPMQswCQYD +VQQGEwJVUzEQMA4GA1UEBwwHU2VhdHRsZTETMBEGA1UECAwKV2FzaGluZ3RvbjEi +MCAGA1UECgwZQW1hem9uIFdlYiBTZXJ2aWNlcywgSW5jLjETMBEGA1UECwwKQW1h +em9uIFJEUzEgMB4GA1UEAwwXQW1hem9uIFJEUyBSb290IDIwMTkgQ0EwHhcNMTkw +ODIyMTcwODUwWhcNMjQwODIyMTcwODUwWjCBjzELMAkGA1UEBhMCVVMxEDAOBgNV +BAcMB1NlYXR0bGUxEzARBgNVBAgMCldhc2hpbmd0b24xIjAgBgNVBAoMGUFtYXpv +biBXZWIgU2VydmljZXMsIEluYy4xEzARBgNVBAsMCkFtYXpvbiBSRFMxIDAeBgNV +BAMMF0FtYXpvbiBSRFMgUm9vdCAyMDE5IENBMIIBIjANBgkqhkiG9w0BAQEFAAOC +AQ8AMIIBCgKCAQEArXnF/E6/Qh+ku3hQTSKPMhQQlCpoWvnIthzX6MK3p5a0eXKZ +oWIjYcNNG6UwJjp4fUXl6glp53Jobn+tWNX88dNH2n8DVbppSwScVE2LpuL+94vY +0EYE/XxN7svKea8YvlrqkUBKyxLxTjh+U/KrGOaHxz9v0l6ZNlDbuaZw3qIWdD/I +6aNbGeRUVtpM6P+bWIoxVl/caQylQS6CEYUk+CpVyJSkopwJlzXT07tMoDL5WgX9 +O08KVgDNz9qP/IGtAcRduRcNioH3E9v981QO1zt/Gpb2f8NqAjUUCUZzOnij6mx9 +McZ+9cWX88CRzR0vQODWuZscgI08NvM69Fn2SQIDAQABo2MwYTAOBgNVHQ8BAf8E +BAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUc19g2LzLA5j0Kxc0LjZa +pmD/vB8wHwYDVR0jBBgwFoAUc19g2LzLA5j0Kxc0LjZapmD/vB8wDQYJKoZIhvcN +AQELBQADggEBAHAG7WTmyjzPRIM85rVj+fWHsLIvqpw6DObIjMWokpliCeMINZFV +ynfgBKsf1ExwbvJNzYFXW6dihnguDG9VMPpi2up/ctQTN8tm9nDKOy08uNZoofMc +NUZxKCEkVKZv+IL4oHoeayt8egtv3ujJM6V14AstMQ6SwvwvA93EP/Ug2e4WAXHu +cbI1NAbUgVDqp+DRdfvZkgYKryjTWd/0+1fS8X1bBZVWzl7eirNVnHbSH2ZDpNuY +0SBd8dj5F6ld3t58ydZbrTHze7JJOd8ijySAp4/kiu9UfZWuTPABzDa/DSdz9Dk/ +zPW4CXXvhLmE02TA9/HeCw3KEHIwicNuEfw= +-----END CERTIFICATE----- +``` + +#### An example with Docker? + +Dockerfiles often rely on Alpine, which does not includes CA certificates by default. +Some providers, like AWS, will also self-sign CA certificates. In that case, it's +up to you to provide the correct certificate. Here's an example of some Docker +steps to provide the correct certificate. + +```dockerfile +# Update your package manager. +RUN apt update +# Add the main CA certificates. +RUN apt install -y ca-certificates inotify-tools curl +# Get the latest CA certificates. +RUN update-ca-certificates +# Get the certificate form AWS. +RUN mkdir -p /aws-certificates +RUN curl -o /aws-certificates/rds.pem https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem +# Provide the CA certificate in the OS directly. +RUN cat /aws-certificates/rds.pem >> /etc/ssl/certs/ca-certificates.crt +``` diff --git a/gleam.toml b/gleam.toml index 1ee3464..0364c55 100644 --- a/gleam.toml +++ b/gleam.toml @@ -10,6 +10,11 @@ links = [ { title = "Sponsor", href = "https://github.com/sponsors/lpil" }, ] +[documentation] +pages = [ + { title = "Solving SSL issues", path = "docs/solving-ssl-issues.html", source = "docs/solving-ssl-issues.md" }, +] + [dependencies] gleam_stdlib = ">= 0.20.0 and < 2.0.0" pgo = ">= 0.12.0 and < 2.0.0" diff --git a/src/pog.gleam b/src/pog.gleam index 358d336..6fa30a5 100644 --- a/src/pog.gleam +++ b/src/pog.gleam @@ -60,12 +60,16 @@ pub type Config { ) } -/// The SSL target needed. pub type Ssl { /// Enable SSL connection, but don't check CA certificate. - SslEnabled + /// `SslEnabled` should always be prioritized upon `SslUnsafe`. + /// As it implies, that option is unsafe, so you should use this option only + /// if you know what you're doing. In case `pog` can not find the proper CA + /// certificate, take a look at the README to get some help to inject the CA + /// certificate in your OS. + SslUnsafe /// Enable SSL connection, and check CA certificate. - SslVerify + SslEnabled /// Disable SSL connection. SslDisabled } @@ -262,6 +266,8 @@ fn extract_user_password(userinfo: String) { /// Expects `sslmode` to be `require`, `verify-ca`, `verify-full` or `disable`. /// If `sslmode` is set, but not one of those value, fails. +/// If `sslmode` is `verify-ca` or `verify-full`, returns `SslEnabled`. +/// If `sslmode` is `require`, returns `SslUnsafe`. /// If `sslmode` is unset, returns `SslDisabled`. fn extract_ssl_mode(query: option.Option(String)) { case query { @@ -270,8 +276,8 @@ fn extract_ssl_mode(query: option.Option(String)) { use query <- result.then(uri.parse_query(query)) use sslmode <- result.then(list.key_find(query, "sslmode")) case sslmode { - "require" -> Ok(SslEnabled) - "verify-ca" | "verify-full" -> Ok(SslVerify) + "require" -> Ok(SslUnsafe) + "verify-ca" | "verify-full" -> Ok(SslEnabled) "disable" -> Ok(SslDisabled) _ -> Error(Nil) } diff --git a/src/pog_ffi.erl b/src/pog_ffi.erl index 20436b9..8415b7f 100644 --- a/src/pog_ffi.erl +++ b/src/pog_ffi.erl @@ -27,8 +27,8 @@ coerce(Value) -> default_ssl_options(Host, Ssl) -> case Ssl of ssl_disabled -> {false, []}; - ssl_enabled -> {true, [{verify, verify_none}]}; - ssl_verify -> {true, [ + ssl_unsafe -> {true, [{verify, verify_none}]}; + ssl_enabled -> {true, [ {verify, verify_peer}, {cacerts, public_key:cacerts_get()}, {server_name_indication, binary_to_list(Host)},