-
Notifications
You must be signed in to change notification settings - Fork 138
SSL support
Sync Gateway supports serving SSL. You just need to add two properties to the config file:
-
"SSLCert":A path to a PEM-format file containing an X.509 certificate or a certificate chain. -
"SSLKey":A path to a PEM-format file containing the certificate's matching private key.
If both properties are present, the server will respond to SSL (and only SSL) over both the public and admin ports.
If you don't want to go this route, you can of course instead run the gateway behind another HTTP server that has SSL enabled, configured to forward requests to the gateway. Apache and Nginx are commonly used to do this; the details are beyond the scope of this document.
Certificates are a complex topic. There are basically two routes you can go: request a certificate from a Certificate Authority (CA), or create your own "self-signed" certificate. Each has pluses and minuses.
There are many certificate authorities, like Thawte and GoDaddy, that will be happy to sell you an SSL certificate. What they have in common is that their own root certificates are known to and trusted by operating systems, so any certificate that they sign will also be trusted. You may want to comparison shop before choosing one.
The benefit of a cert obtained from a CA is that it will be trusted by any SSL client. The drawback is that you'll usually have to pay for it, and the more trustworthy you want the cert to be, the more it'll cost and the more hoops you'll have to jump through to prove your identity to the CA.
As part of requesting the certificate, your browser will create a private key locally (the CA never sees the private key.) The CA will then generate the certificate and let you download it. You'll then need to get both the private key and the certificate as individual files in PEM format.
Unlike a CA-signed cert, a self-signed cert isn't intrinsically trustworthy: a client can't tell who you are by examining the cert, because no recognized authority has vouched for it. But a self-signed cert is still unique (only you, as the holder of the private key, can operate a server using that cert), and it still allows the connection to be encrypted.
The most secure way to use a self-signed cert is with "cert pinning": see the section below for details.
It's easy to create a self-signed certificate using the openssl command-line tool and these directions. In a nutshell, you just need to run these commands:
openssl genrsa -out privkey.pem 2048
openssl req -new -x509 -sha256 -key privkey.pem -out cert.pem -days 1095
The second command is interactive and will ask you for information like country and city name that goes into the X.509 certificate. You can put whatever you want there; the only important part is the field Common Name (e.g. server FQDN or YOUR name) which needs to be the exact hostname that clients will reach your server at. The client will verify that this name matches the hostname in the URL it's trying to access, and will reject the connection if it doesn't.
The tool will then create two files: privkey.pem (the private key) and cert.pem (the public certificate.)
To create a copy of the cert in binary DER format (often stored in a ".cer" file), do this:
openssl x509 -inform PEM -in cert.pem -outform DER -out cert.cer
Whichever way you obtained the cert, you will now have a private key and an X.509 certificate. Ensure that they're in separate files and in PEM format, and put them in a directory that's readable by the Sync Gateway process. The private key is very sensitive (it's not encrypted) so make sure the file isn't readable by unauthorized processes.
Then just add the "SSLCert" and "SSLKey" properties to your Sync Gateway configuration file, as shown up above.
The most secure way for your client app to connect to your server is for it to embed a copy of the X.509 certificate file (but not the private key!) At runtime it then loads the cert into memory and instructs the Couchbase Lite replicator to accept only that cert, via the setAnchorCerts method. This ensures that your app can only connect to your own server: even if an attacker were able to forge a CA-signed cert for your domain, its cert will have a different public key, so the replicator will reject it.
Cert pinning is most useful with self-signed certs, because without it the app has no way to trust that it's connected to your own server and not some other server masquerading as it. But it also improves security when used with a CA cert, because CAs can sometimes be hacked or tricked into issuing bogus certificates, in which case an attacker could create a fake certificate with your server's hostname and use it (in conjunction with DNS spoofing) to masquerade as your server. So far this type of attack has only been used against very high-profile sites, but better safe than sorry!