CLOUDSTACK-4151: move the about encryption out of the installation instruction
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/repo Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/commit/ec47bf07 Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/tree/ec47bf07 Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/diff/ec47bf07 Branch: refs/heads/master Commit: ec47bf07ab2951eb73d5cae92435f5bcb4bab79a Parents: e9ce9df Author: Pierre-Luc Dion <[email protected]> Authored: Sat Mar 7 11:11:48 2015 -0500 Committer: Pierre-Luc Dion <[email protected]> Committed: Sat Mar 7 11:11:48 2015 -0500 ---------------------------------------------------------------------- source/encryption.rst | 118 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cloudstack-docs-install/blob/ec47bf07/source/encryption.rst ---------------------------------------------------------------------- diff --git a/source/encryption.rst b/source/encryption.rst new file mode 100644 index 0000000..75877c0 --- /dev/null +++ b/source/encryption.rst @@ -0,0 +1,118 @@ + +.. _about-password-key-encryption: + +About Password and Key Encryption +--------------------------------- + +CloudStack stores several sensitive passwords and secret keys that are +used to provide security. These values are always automatically +encrypted: + +- Database secret key + +- Database password + +- SSH keys + +- Compute node root password + +- VPN password + +- User API secret key + +- VNC password + +CloudStack uses the Java Simplified Encryption (JASYPT) library. The +data values are encrypted and decrypted using a database secret key, +which is stored in one of CloudStackâs internal properties files along +with the database password. The other encrypted values listed above, +such as SSH keys, are in the CloudStack internal database. + +Of course, the database secret key itself can not be stored in the open +â it must be encrypted. How then does CloudStack read it? A second +secret key must be provided from an external source during Management +Server startup. This key can be provided in one of two ways: loaded from +a file or provided by the CloudStack administrator. The CloudStack +database has a configuration setting that lets it know which of these +methods will be used. If the encryption type is set to "file," the key +must be in a file in a known location. If the encryption type is set to +"web," the administrator runs the utility +com.cloud.utils.crypt.EncryptionSecretKeySender, which relays the key to +the Management Server over a known port. + +The encryption type, database secret key, and Management Server secret +key are set during CloudStack installation. They are all parameters to +the CloudStack database setup script (cloudstack-setup-databases). The +default values are file, password, and password. It is, of course, +highly recommended that you change these to more secure keys. + + +Changing the Default Password Encryption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Passwords are encoded when creating or updating users. CloudStack allows +you to determine the default encoding and authentication mechanism for +admin and user logins. Two new configurable lists have been +introducedâuserPasswordEncoders and userAuthenticators. +userPasswordEncoders allows you to configure the order of preference for +encoding passwords, whereas userAuthenticators allows you to configure +the order in which authentication schemes are invoked to validate user +passwords. + +Additionally, the plain text user authenticator has been modified not to +convert supplied passwords to their md5 sums before checking them with +the database entries. It performs a simple string comparison between +retrieved and supplied login passwords instead of comparing the +retrieved md5 hash of the stored password against the supplied md5 hash +of the password because clients no longer hash the password. The +following method determines what encoding scheme is used to encode the +password supplied during user creation or modification. + +When a new user is created, the user password is encoded by using the +first valid encoder loaded as per the sequence specified in the +``UserPasswordEncoders`` property in the ``ComponentContext.xml`` or +``nonossComponentContext.xml`` files. The order of authentication +schemes is determined by the ``UserAuthenticators`` property in the same +files. If Non-OSS components, such as VMware environments, are to be +deployed, modify the ``UserPasswordEncoders`` and ``UserAuthenticators`` +lists in the ``nonossComponentContext.xml`` file, for OSS environments, +such as XenServer or KVM, modify the ``ComponentContext.xml`` file. It +is recommended to make uniform changes across both the files. When a new +authenticator or encoder is added, you can add them to this list. While +doing so, ensure that the new authenticator or encoder is specified as a +bean in both these files. The administrator can change the ordering of +both these properties as preferred to change the order of schemes. +Modify the following list properties available in +``client/tomcatconf/nonossComponentContext.xml.in`` or +``client/tomcatconf/componentContext.xml.in`` as applicable, to the +desired order: + +.. sourcecode:: xml + + <property name="UserAuthenticators"> + <list> + <ref bean="SHA256SaltedUserAuthenticator"/> + <ref bean="MD5UserAuthenticator"/> + <ref bean="LDAPUserAuthenticator"/> + <ref bean="PlainTextUserAuthenticator"/> + </list> + </property> + <property name="UserPasswordEncoders"> + <list> + <ref bean="SHA256SaltedUserAuthenticator"/> + <ref bean="MD5UserAuthenticator"/> + <ref bean="LDAPUserAuthenticator"/> + <ref bean="PlainTextUserAuthenticator"/> + </list> + </property> + +In the above default ordering, SHA256Salt is used first for +``UserPasswordEncoders``. If the module is found and encoding returns a +valid value, the encoded password is stored in the user table's password +column. If it fails for any reason, the MD5UserAuthenticator will be +tried next, and the order continues. For ``UserAuthenticators``, +SHA256Salt authentication is tried first. If it succeeds, the user is +logged into the Management server. If it fails, md5 is tried next, and +attempts continues until any of them succeeds and the user logs in . If +none of them works, the user is returned an invalid credential message. +
