Created Authentication used in the Subsonic API (markdown)

Authentication-used-in-the-Subsonic-API.md

@@ -0,0 +1,53 @@
+The Subsonic-like servers use two distinct format of authentication, usually based on what version of the Subsonic API they support. These are called Plain Password (or LDAP), and Token-based. Ultrasonic tries to use the slightly more secure Token-based if it is available, but the servers not always support that - the Subsonic error "Authentication by token is not supported for LDAP users" tries to tell this.  
+
+If Authentication by Token is not supported, you can try the plain password one by turning "Force plain password authentication" on. Also, if your server only supports Tokens (e.g. like Ampache when configured to use API Keys), turn this setting off.  
+
+### What is the difference between the two methods
+
+**Plain Password**, as its name says, sends the user's password together with the request to the server in plain text. This means that the password is readable in the request header if someone would check.  
+
+**Token based** authentication uses an MD5 checksum created from the password and a salt value for authentication. This "token" is sent to the server in the requests, so it is not entirely trivial (by eye) to tell the user's password from it.
+
+### Which is more secure
+
+Neither of them, really. MD5 is not considered to be secure, so it is very easy to retrieve a working password if you have the token. But also, if you have the token, you can send valid, authenticated requests to the server with it by using a tool like curl.  
+
+The only really secure layer you can add here is by enabling TLS with a server certificate on your server, and connecting by using HTTPS.  
+You can create your own self-signed certificate to do this, in which case you must **enable self-signed certificates** in Ultrasonic. But it is really easy to get a real certificate from a free provider, for example [Let's Encrypt](https://letsencrypt.org/).  
+
+If you use TLS, your communication will be encrypted to the server, and you can be sure no-one will see your password even on public wifi networks for example.
+
+### What any of this has to do with LDAP
+
+It is a common feature of Subsonic-like servers to connect to an LDAP server for user authentication. In this case the LDAP server is the central place where the user credentials are configured and stored, which is nice because the user can use the same credentials with multiple applications which are connected to the LDAP server.
+
+However, when the Subsonic API is configured to use the Token-based authentication, the server needs to know the user's password to verify the token. During Token verification the server tries to generate the same token from the salt and the user's plain password, and if the two tokens match, the authentication is successful.  
+
+You can see where this is going - if the Subsonic server uses LDAP authentication, the user's password is stored in the LDAP server, so it can't be used to generate the verification token on the Subsonic server. When a Subsonic server is configured to use LDAP, the clients must send the password in plain text, because the token can't be verified.
+
+### How Subsonic-like servers store passwords
+
+Token-based authentication presents another problem: if the server needs the user's plain password to verify the token received from the client, that means the user's plain password must be stored inside the server. This is a big security risk, and responsible server developers try to avoid it.
+
+Usually passwords are stored on the server side databases using slow one-way hash algorithms like PBKDF2, which helps in cases when an attacker gains access to and possibly copies the database of a server. One-way algorithm means that a hash can be generated from the password, but the password can't be retrieved from the hash - and it can't be used for token validation.
+
+Subsonic-like servers have a few solution to this problem:
+- They store the password in a format from which its value is easily retrieved (like good old Subsonic once did as a hexadecimal string)  
+  In this case there is no problem, the clients can use plain password or token based authentication as they like.
+- They store the password's secure hash, as it is recommended nowadays  
+  These servers can only use plain password authentication by default. Some of them are able to assign "API Tokens" for users, which they store in a retrievable format - these servers can work with token based authentication after the correct setup. Be sure to enter the API Token in Ultrasonic, and not your password which you use to log in to the server otherwise.
+- They store the password using a "decodable credential encoder" (like AES or AES-GCM)  
+  These servers can decrypt the stored password and use it for token verification, so they support both plain password and token-based authentication. However, if you're paranoid, you should know that the cryptographic key they use to encrypt the password in the database is usually not too well hidden, and an attacker can steal it together with the password database.  
+
+As you can see, there are usually multiple configuration options on both the server and the client side, and it is very easy to end up with something that isn't working or isn't secure.
+
+### What is the best practice
+DISCLAIMER: Please always follow industry security best practices when you configure your server and your client. We won't take any responsibility if your data is stolen or your account is compromised in any way.  
+
+That out of the way, some tips:
+- Always use a separate, strong password for your Subsonic user account. If you can't remember so much strong passwords, use a password manager (like for example [KeePass](https://keepass.info/))
+- Do not use your administrator account to access your Subsonic server from Ultrasonic. Create a separate account for music playback with restricted rights
+- Configure TLS with your server using a certificate signed by a CA, and use HTTPS to connect to your server
+- The Subsonic ecosystem was designed not to be so security focused, because it's just a media server. Never store any sensitive data on your media server. Always create backups of your media files.
+- Allow your server to store the passwords in its database the most secure way possible. Its better to use Plain Password authentication on the Subsonic API with a properly configured TLS than to enable Token-based authentication and store your passwords insecurely in the database
+