Skip to content

Commit

Permalink
Improve SSL documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ghivert
ghivert committed Nov 27, 2024
1 parent cb15cfc commit da4c813
Show file tree
Hide file tree
Showing 5 changed files with 213 additions and 125 deletions.
185 changes: 67 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,125 +110,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-----
```
128 changes: 128 additions & 0 deletions docs/solving-ssl-issues.md
View file
Original file line number Diff line number Diff line change
@@ -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
```
5 changes: 5 additions & 0 deletions gleam.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
16 changes: 11 additions & 5 deletions src/pog.gleam
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down Expand Up @@ -259,6 +263,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 {
Expand All @@ -267,8 +273,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)
}
Expand Down
4 changes: 2 additions & 2 deletions src/pog_ffi.erl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)},
Expand Down

0 comments on commit da4c813

Please sign in to comment.