X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=doc%2FSSL.md;h=d3f5ecc895afb528e6de3ecb60341e91b4765091;hb=13a4483c59d916b48f9585beb7f5a71328055b72;hp=0067206e5f173ab5dc716a5149c2ac36574d9bd6;hpb=5f80467a8f83250354cf4d0a4889ae78c03c0146;p=friendica.git
diff --git a/doc/SSL.md b/doc/SSL.md
index 0067206e5f..d3f5ecc895 100644
--- a/doc/SSL.md
+++ b/doc/SSL.md
@@ -3,166 +3,94 @@ Using SSL with Friendica
* [Home](help)
-If you are running your own Friendica site, you may want to use SSL (https) to encrypt communication between yourself and your server (communication between servers is encrypted anyway).
+## Disclaimer
-To do that on a domain of your own, you have to obtain a certificate from a trusted organization (so-called self-signed certificates that are popular among geeks donât work very well with Friendica, because they can cause disturbances in other people's browsers).
+**This document has been updated in November 2016.
+SSL encryption is relevant for security.
+This means that recommended settings change fast.
+Keep your setup up to date and do not rely on this document being updated as fast as technologies change!**
-If you are reading this document before actually installing Friendica, you might want to consider a very simple option: Go for a shared hosting account without your own domain name. That way, your address will be something like yourname.yourprovidersname.com, which isn't very fancy compared to yourname.com. But it will still be your very own site, and you will usually be able to hitch a lift on your provider's SSL certificate. That means that you won't need to configure SSL at all - it will simply work out of the box when people type https instead of http.
+## Intro
-If that isn't your idea of doing things, read on...
+If you are running your own Friendica site, you may want to use SSL (https) to encrypt communication between servers and between yourself and your server.
-**Shared hosts**
+There are basically two sorts of SSL certificates: Self-signed certificates and certificates signed by a certificate authority (CA).
+Technically, both provide the same valid encryption.
+There is a problem with self-signed certificates though:
+They are neither installed in browsers nor on other servers.
+That is why they provoke warnings about "mistrusted certificates".
+This is confusing and disturbing.
-If you are using a shared host on a domain of your own, your provider may well offer to obtain and install the certificate for you. You will then only need to apply and pay for it â and everything will be set up. If that is the case for you, the rest of this document need not concern you at all. Just make sure the certificate is for the address that Friendica uses: e.g. myownfriendica.com or friendica.myserver.com.
+For this reason, we recommend to get a certificate signed by a CA.
+Normally, you have to pay for them - and they are valid for a limited period of time (e.g. a year or two).
-The above ought to be the most common scenario for Friendica sites, making the rest of this article superfluous for most people.
+There are ways to get a trusted certificate for free.
-**Obtaining a certificate yourself**
+## Choose your domain name
-Alternatively, a few shared hosting providers may ask you to obtain and upload the certificate yourself.
+Your SSL certificate will be valid for a domain or even only for a subdomain.
+Make your final decision about your domain resp. subdomain *before* ordering the certificate.
+Once you have it, changing the domain name means getting a new certificate.
-The next section describes the process of acquiring a certificate from StartSSL. The good thing about StartSSL is that you can get an entry-level, but perfectly sufficient certificate for free. Thatâs not the case with most other certificate issuers - so we will be concentrating on StartSSL in this document If you want to use a certificate from a different source, you will have to follow the instructions given by that organization. We can't cover every possibility here.
+### Shared hosts
-Installing your certificate - once you have obtained it - depends on your providerâs way of doing things. But for shared hosts, there will usually be an easy web tool for this.
+If your Friendica instance is running on a shared hosting platform, you should first check with your hosting provider.
+They have instructions for you on how to do it there.
+You can always order a paid certificate with your provider.
+They will either install it for you or provide an easy way to upload the certificate and the key via a web interface.
+With some providers, you have to send them your certificate.
+They need the certificate, the key and the CA's intermediate certificate.
+To be sure, send those three files.
+**You should send them to your provider via an encrypted channel!**
-Note: Your certificate is usually restricted to one subdomain. When you apply for the certificate, make sure itâs for the domain and subdomain Friendica uses: e.g. myownfriendica.com or friendica.myserver.com.
+### Own server
-**Getting a free StartSSL certificate**
+If you run your own server, we recommend to check out the ["Let's Encrypt" initiative](https://letsencrypt.org/).
+Not only do they offer free SSL certificates, but also a way to automate their renewal.
+You need to install a client software on your server to use it.
+Instructions for the official client are [here](https://certbot.eff.org/).
+Depending on your needs, you might want to look at the [list of alternative letsencrypt clients](https://letsencrypt.org/docs/client-options/).
-StartSSLâs website attempts to guide you through the process of obtaining a free certificate, but some people end up frustrated. We really recommend working your way through the steps on the site very slowly and carefully. Don't take things for granted - read every word before proceeding and don't close the browser window until everything is working. That said, there are three main stumbling blocks that can confuse users:
+## Web server settings
-When you initially sign up with StartSSL, the first certificate you receive is simply installed in your browser (though you should also store it somewhere safe, so that you can reinstall it in any other browser at a later date, for instance when you need to renew something). This authentication certificate is only used for logging on to the StartSSL website â it has nothing to do with the certificate you will need for your server. As a first-timer with StartSSL, start here: https://www.startssl.com/?app=12 and choose the Express Lane option to get that browser authentication certificate. Then seamlessly continue to the process of acquiring the desired certificate for your server (the one you actually came for). You can change the websiteâs language if that makes things easier for you.
+Visit the [Mozilla's wiki](https://wiki.mozilla.org/Security/Server_Side_TLS) for instructions on how to configure a secure webserver.
+They provide recommendations for [different web servers](https://mozilla.github.io/server-side-tls/ssl-config-generator/).
-When you are first prompted for a domain to certify, you need to enter your top-level domain â not the subdomain Friendica uses. In the next step, you will be able to specify that subdomain. So if you have friendica.yourname.com on your server, you first enter yourname.com â and specify the subdomain friendica later.
+## Test your SSL settings
-Donât quit too fast when you have received your personal web server certificate at the end of the procedure. Depending on your server software, you will also require one or two generic files for use with this free StartSSL certificate. These are sub.class1.server.ca.pem and ca.pem. If you have already overlooked this step, you can download those files here: http://www.startssl.com/?app=21 But once again, the very best way of doing things is not to quit the StartSSL site until you are completely done and your https certificate is up and working.
+When you are done, visit the test site [SSL Labs](https://www.ssllabs.com/ssltest/) to have them check if you succeeded.
-**Virtual private and dedicated servers (using StartSSL free)**
+## Configure Friendica
-The rest of this document is slightly more complicated, but itâs only for people running Friendica on a virtual private or dedicated server. Everyone else can stop reading at this point.
+If you can successfully access your Friendica instance through https, there are a number of steps you can take to ensure your users will use SSL to access your instance.
-Follow the instructions here ( http://www.startssl.com/?app=20 ) to configure the web server you are using (e.g. Apache) for your certificate.
+### Web server redirection
-To illustrate the necessary changes, we will now assume you are running Apache. In essence, you can simply create a second httpd.conf entry for Friendica.
+This is the simplest way to enforce site-wide secure access.
+Every time a user tries to access any Friendica page by any mean (manual address bar entry or link), the web server issues a Permanent Redirect response with the secure protocol prepended to the requested URL.
-To do this, you copy the existing one and change the end of the first line to read :443> instead of :80>, then add the following lines to that entry, as also shown in StartSSLâs instructions:
+With Apache, enable the modules rewrite and ssl (with a shared hosting provider, this should be enabled already):
- SSLEngine on
- SSLProtocol all -SSLv2
- SSLCipherSuite ALL:!ADH:!EXPORT:!SSLv2:RC4+RSA:+HIGH:+MEDIUM
+ sudo a2enmod rewrite ssl
- SSLCertificateFile /usr/local/apache/conf/ssl.crt
- SSLCertificateKeyFile /usr/local/apache/conf/ssl.key
- SSLCertificateChainFile /usr/local/apache/conf/sub.class1.server.ca.pem
- SSLCACertificateFile /usr/local/apache/conf/ca.pem
- SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown
- CustomLog /usr/local/apache/logs/ssl_request_log \
- "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
+Add the following lines to the .htaccess file in the root folder of your Friendica instance (thanks to [AlfredSK](https://github.com/AlfredSK)):
-(Note that the directory /usr/local/apache/conf/ may not exist on your machine. For Debian, for instance, the directory might be /etc/apache2/ - in which you can create an ssl subdirectory if it doesnât already exist. Then you have /etc/apache2/ssl/⦠instead of /usr/local/apache/conf/â¦)
+ RewriteEngine On
+ RewriteCond %{SERVER_PORT} 80
+ RewriteRule ^(.*)$ https://your.friendica.domain/$1 [R=301,L]
-You thus end up with two entries for your Friendica site - one for simple http and one for https.
+With nginx, configure your server directive this way ([documentation](https://www.nginx.com/blog/creating-nginx-rewrite-rules/)):
-Note to those who want to force SSL: Don't redirect to SSL in your Apache settings. Friendica's own admin panel has a special setting for SSL policy. Please use this facility instead.
+ server {
+ listen 80;
+ server_name your.friendica.domain;
+ return 301 https://$server_name$request_uri;
+ }
-**Mixing certificates on Apache â StartSSL and others (self-signed)**
+### SSL Settings
-Many people using a virtual private or dedicated server will be running more than Friendica on it. They will probably want to use SSL for other sites they run on the server, too. To achieve this, they may wish to employ more than one certificate with a single IP â for instance, a trusted one for Friendica and a self-signed certificate for personal stuff (possibly a wildcard certificate covering arbitrary subdomains).
+In the Admin Settings, there are three SSL-related settings:
-For this to work, Apache offers a NameVirtualHost directive. You can see how to use it in httpd.conf in the following pattern. Note that wildcards (*) in httpd.conf break the NameVirtualHost method â you canât use them in this new configuration. In other words, no more *80> or *443>. And you really must specify the IP, too, even if you only have one. Also note that you will soon be needing two additional NameVirtualHost lines at the top of the file to cater for IPv6.
-
- NameVirtualHost 12.123.456.1:443
- NameVirtualHost 12.123.456.1:80
-
-
- DocumentRoot /var/www/anywhere
- Servername www.anywhere.net
-
-
-
- DocumentRoot /var/www/anywhere
- Servername www.anywhere.net
- SSLEngine On
-
-
-
-
-
-
- DocumentRoot /var/www/somewhere-else
- Servername www.somewhere-else.net
-
-
-
- DocumentRoot /var/www/somewhere-else
- Servername www.somewhere-else.net
- SSLEngine On
-
-
-
-
-
-Of course, you may optionally be using other places like the sites-available directory to configure Apache, in which case only some of this information need be in httpd.conf or ports.conf - specifically, the NameVirtualHost lines must be there. But if you're savvy about alternatives like that, you will probably be able to figure out the details yourself.
-
-Just restart Apache when you're done, whichever way you decide to do it.
-
-**StartSSL on Nginx**
-
-First, update to the latest Friendica code. Then follow the above instructions to get your free certificate. But instead of following the Apache installation instructions, do this:
-
-Upload your certificate. It doesn't matter where to, as long as Nginx can find it. Some people use /home/randomlettersandnumbers to keep it in out of paranoia, but you can put it anywhere, so we'll call it /foo/bar.
-
-You can remove the password if you like. This is probably bad practice, but if you don't, you'll have to enter the password every time you restart nginx. To remove it:
-
- openssl rsa -in ssl.key-pass -out ssl.key
-
-Now, grab the helper certificate:
-
- wget http://www.startssl.com/certs/sub.class1.server.ca.pem
-
-Now you need to merge the files:
-
- cat ssl.crt sub.class1.server.ca.pem > ssl.crt
-
-In some configurations there is a bug, and this doesn't quite work properly. You may now need to edit ssl.crt, so:
-
- nano /foo/bar/ssl.crt
-
-You'll see two certificates in the same file. Halfway down, you may see:
-
- -----END CERTIFICATE----------BEGIN CERTIFICATE-----
-
-This is bad. You need to see:
-
- -----END CERTIFICATE-----
- -----BEGIN CERTIFICATE-----
-
-You can enter the carriage return manually if the bug is present on your system. Note there is a single carriage return for -----BEGIN CERTIFICATE----- to start on a new line. There is no empty line.
-
-Now you need to tell Nginx about the certs.
-
-In /etc/nginx/sites-available/foo.com.conf you need something like:
-
- server {
-
- listen 80;
-
- listen 443 ssl;
-
- listen [::]:80;
-
- listen [::]:443 ipv6only=on ssl;
-
- ssl_certificate /foo/bar/ssl.crt;
-
- ssl_certificate_key /foo/bar/ssl.key;
-
- ...
-
-Now, restart nginx:
-
- /etc/init.d/nginx restart
-
-And that's it.
-
-For multiple domains, we have it easier than Apache users: Just repeat the above for each certificate, and keep it in it's own {server...} section.
\ No newline at end of file
+1. **SSL link policy**: this affects how Friendica generates internal links. If your SSL installation was successful, we recommend "Force all links to SSL" just in case your web server configuration can't be altered like described above.
+2. **Force SSL**: This forces all external links to HTTPS, which may solve Mixed-Content issues, but not all websites support HTTPS yet. Use at your own risk.
+3. **Verify SSL**: Enabling this will prevent Friendica to interact with self-signed SSL sites. We recommend you leave it on as a self-signed SSL certificate can be a vectorfor a man-in-the-middle attack.