Add various SSL modes

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Add support for `sslmode` in connection strings.
+- Change SSL from `Bool` to `SslVerify`, `SslUnverify` and `SslDisabled` to match
+  against diverse CA certificates or not.
+
 ## v1.1.0 - 2024-12-11
 
 - Added support for timeout in pool configuration as well as queries.

README.md

@@ -120,6 +120,73 @@ 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`, `SslUnverified` &
+`SslVerified`. 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.SslVerified)
+  |> 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

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.SslUnverified`. 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
+```

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"

src/pog.gleam

@@ -26,8 +26,8 @@ pub type Config {
     user: String,
     /// Password for the user.
     password: Option(String),
-    /// (default: False): Whether to use SSL or not.
-    ssl: Bool,
+    /// (default: SslDisabled): Whether to use SSL or not.
+    ssl: Ssl,
     /// (default: []): List of 2-tuples, where key and value must be binary
     /// strings. You can include any Postgres connection parameter here, such as
     /// `#("application_name", "myappname")` and `#("timezone", "GMT")`.
@@ -60,6 +60,24 @@ pub type Config {
   )
 }
 
+pub type Ssl {
+  /// Enable SSL connection, and check CA certificate. It is the most secured
+  /// option to use SSL and should be always used by default.
+  /// Never ignore CA certificate checking _unless you know exactly what you are
+  /// doing_.
+  SslVerified
+  /// Enable SSL connection, but don't check CA certificate.
+  /// `SslVerified` should always be prioritized upon `SslUnverified`.
+  /// As it implies, that option enables SSL, but as it is unverified, the
+  /// connection can be unsafe. _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.
+  SslUnverified
+  /// Disable SSL connection completely. Using this option will let the
+  /// connection unsecured, and should be avoided in production environment.
+  SslDisabled
+}
+
 /// Database server hostname.
 ///
 /// (default: 127.0.0.1)
@@ -92,7 +110,7 @@ pub fn password(config: Config, password: Option(String)) -> Config {
 /// Whether to use SSL or not.
 ///
 /// (default: False)
-pub fn ssl(config: Config, ssl: Bool) -> Config {
+pub fn ssl(config: Config, ssl: Ssl) -> Config {
   Config(..config, ssl:)
 }
 
@@ -189,7 +207,7 @@ pub fn default_config() -> Config {
     database: "postgres",
     user: "postgres",
     password: None,
-    ssl: False,
+    ssl: SslDisabled,
     connection_parameters: [],
     pool_size: 10,
     queue_target: 50,
@@ -205,27 +223,25 @@ pub fn default_config() -> Config {
 /// Parse a database url into configuration that can be used to start a pool.
 pub fn url_config(database_url: String) -> Result(Config, Nil) {
   use uri <- result.then(uri.parse(database_url))
-  use #(userinfo, host, path, db_port) <- result.then(case uri {
+  use #(userinfo, host, path, db_port, query) <- result.then(case uri {
     Uri(
       scheme: Some(scheme),
       userinfo: Some(userinfo),
       host: Some(host),
       port: Some(db_port),
       path: path,
+      query: query,
       ..,
     ) -> {
       case scheme {
-        "postgres" | "postgresql" -> Ok(#(userinfo, host, path, db_port))
+        "postgres" | "postgresql" -> Ok(#(userinfo, host, path, db_port, query))
         _ -> Error(Nil)
       }
     }
     _ -> Error(Nil)
   })
-  use #(user, password) <- result.then(case string.split(userinfo, ":") {
-    [user] -> Ok(#(user, None))
-    [user, password] -> Ok(#(user, Some(password)))
-    _ -> Error(Nil)
-  })
+  use #(user, password) <- result.then(extract_user_password(userinfo))
+  use ssl <- result.then(extract_ssl_mode(query))
   case string.split(path, "/") {
     ["", database] ->
       Ok(
@@ -236,12 +252,45 @@ pub fn url_config(database_url: String) -> Result(Config, Nil) {
           database: database,
           user: user,
           password: password,
+          ssl: ssl,
         ),
       )
     _ -> Error(Nil)
   }
 }
 
+/// Expects `userinfo` as `"username"` or `"username:password"`. Fails otherwise.
+fn extract_user_password(
+  userinfo: String,
+) -> Result(#(String, Option(String)), Nil) {
+  case string.split(userinfo, ":") {
+    [user] -> Ok(#(user, None))
+    [user, password] -> Ok(#(user, Some(password)))
+    _ -> Error(Nil)
+  }
+}
+
+/// 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 `SslVerified`.
+/// If `sslmode` is `require`, returns `SslUnverified`.
+/// If `sslmode` is unset, returns `SslDisabled`.
+fn extract_ssl_mode(query: option.Option(String)) -> Result(Ssl, Nil) {
+  case query {
+    option.None -> Ok(SslDisabled)
+    option.Some(query) -> {
+      use query <- result.then(uri.parse_query(query))
+      use sslmode <- result.then(list.key_find(query, "sslmode"))
+      case sslmode {
+        "require" -> Ok(SslUnverified)
+        "verify-ca" | "verify-full" -> Ok(SslVerified)
+        "disable" -> Ok(SslDisabled)
+        _ -> Error(Nil)
+      }
+    }
+  }
+}
+
 /// A pool of one or more database connections against which queries can be
 /// made.
 ///

src/pog_ffi.erl

@@ -26,15 +26,16 @@ coerce(Value) ->
 %% will not be handled correctly.
 default_ssl_options(Host, Ssl) ->
   case Ssl of
-    false -> [];
-    true -> [
+    ssl_disabled -> {false, []};
+    ssl_unsafe -> {true, [{verify, verify_none}]};
+    ssl_enabled -> {true, [
       {verify, verify_peer},
       {cacerts, public_key:cacerts_get()},
       {server_name_indication, binary_to_list(Host)},
       {customize_hostname_check, [
         {match_fun, public_key:pkix_verify_hostname_match_fun(https)}
       ]}
-    ]
+    ]}
   end.
 
 connect(Config) ->
@@ -57,13 +58,13 @@ connect(Config) ->
         rows_as_map = RowsAsMap,
         default_timeout = DefaultTimeout
     } = Config,
-    SslOptions = default_ssl_options(Host, Ssl),
+    {SslActivated, SslOptions} = default_ssl_options(Host, Ssl),
     Options1 = #{
         host => Host,
         port => Port,
         database => Database,
         user => User,
-        ssl => Ssl,
+        ssl => SslActivated,
         ssl_options => SslOptions,
         connection_parameters => ConnectionParameters,
         pool_size => PoolSize,