From f2fc387c7bd95311da1c09b6a9cfaa9ad8377b09 Mon Sep 17 00:00:00 2001 From: Daan Hoogland Date: Thu, 23 Jul 2026 10:27:12 +0200 Subject: [PATCH 1/2] rabbitmq jasypt instructions update --- source/adminguide/events.rst | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/source/adminguide/events.rst b/source/adminguide/events.rst index b3444730e0..379f60838d 100644 --- a/source/adminguide/events.rst +++ b/source/adminguide/events.rst @@ -162,10 +162,20 @@ changes can control the behaviour. The ``eventNotificationBus`` bean represents the ``org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus`` class. - + If you want to use encrypted values for the username and password, you have to include a bean to pass those as variables from a credentials file. + .. note:: + Older versions of this guide referenced + ``org.jasypt.spring3.properties.EncryptablePropertyPlaceholderConfigurer``, which comes + from the ``jasypt-spring3`` artifact. That artifact is not shipped with CloudStack and is + not compatible with the Spring 5 used since CloudStack 4.x, so beans referencing it fail + to load with a ``ClassNotFoundException``. Use + ``com.cloud.utils.crypt.EncryptablePropertyPlaceholderConfigurer`` instead, which ships + with CloudStack and works the same way. This bean also expects encrypted values to be + wrapped as ``ENC(...)``, matching the convention used elsewhere in CloudStack. + A sample is given below .. code:: bash @@ -191,29 +201,39 @@ changes can control the behaviour. - + + + + - + - Create a new file in the same folder called ``cred.properties`` and the specify the values for username and password as jascrypt encrypted strings + Create a new file in the same folder called ``cred.properties`` and specify the values for + username and password as jasypt encrypted strings, wrapped as ``ENC(...)``. Sample, with ``guest`` as values for both fields: .. code:: bash - username=nh2XrM7jWHMG4VQK18iiBQ== - password=nh2XrM7jWHMG4VQK18iiBQ== + username=ENC(nh2XrM7jWHMG4VQK18iiBQ==) + password=ENC(nh2XrM7jWHMG4VQK18iiBQ==) + + ``PBEWithMD5AndDES``, used in earlier releases of this guide, is a weak algorithm and should + not be used for new deployments; ``PBEWITHHMACSHA512ANDAES_256`` above is a stronger, + future-proof alternative. Use the ``jasypt`` CLI tools (or any tool using the jasypt library) + with the same algorithm, IV generator and ``APP_ENCRYPTION_PASSWORD`` to produce the + encrypted values for ``cred.properties``. #. Restart the Management Server. From 316aae1358679b60d1843f8f7a05cab315a42ea3 Mon Sep 17 00:00:00 2001 From: Daan Hoogland Date: Fri, 21 Aug 2026 11:48:33 +0200 Subject: [PATCH 2/2] notes on changing the old encryption method to the updated one --- source/adminguide/events.rst | 62 +++++++++++++++++++----------------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/source/adminguide/events.rst b/source/adminguide/events.rst index 379f60838d..23d2f08b1f 100644 --- a/source/adminguide/events.rst +++ b/source/adminguide/events.rst @@ -163,18 +163,25 @@ changes can control the behaviour. The ``eventNotificationBus`` bean represents the ``org.apache.cloudstack.mom.rabbitmq.RabbitMQEventBus`` class. - If you want to use encrypted values for the username and password, you have to include a bean to pass those - as variables from a credentials file. + If you want to use encrypted values for the username and password, you have to include a + bean that decrypts those values as they're read from a credentials file. CloudStack ships + such a bean, ``com.cloud.utils.crypt.EncryptablePropertyPlaceholderConfigurer``, which + decrypts any property value wrapped as ``ENC(...)`` using the management server's own + secret key, i.e. the same key configured via ``password.encryption.type`` in + ``db.properties`` (see :doc:`management`). No separate encryption library or encryptor + bean is required. .. note:: Older versions of this guide referenced ``org.jasypt.spring3.properties.EncryptablePropertyPlaceholderConfigurer``, which comes - from the ``jasypt-spring3`` artifact. That artifact is not shipped with CloudStack and is - not compatible with the Spring 5 used since CloudStack 4.x, so beans referencing it fail - to load with a ``ClassNotFoundException``. Use - ``com.cloud.utils.crypt.EncryptablePropertyPlaceholderConfigurer`` instead, which ships - with CloudStack and works the same way. This bean also expects encrypted values to be - wrapped as ``ENC(...)``, matching the convention used elsewhere in CloudStack. + from the ``jasypt-spring3`` artifact, configured with a hand-rolled jasypt + ``StringEncryptor`` bean and algorithm. That artifact is not shipped with CloudStack and + is not compatible with the Spring version used since CloudStack 4.x, so beans + referencing it fail to load with a ``ClassNotFoundException`` and the encrypted + credentials are never decrypted. Use + ``com.cloud.utils.crypt.EncryptablePropertyPlaceholderConfigurer`` as shown below + instead; it needs no separate encryptor bean, and reuses the management server's own + secret key rather than a weak, independently configured cipher. A sample is given below @@ -200,40 +207,35 @@ changes can control the behaviour. - - - - - - - - - - - - - Create a new file in the same folder called ``cred.properties`` and specify the values for - username and password as jasypt encrypted strings, wrapped as ``ENC(...)``. + username and password, each encrypted against the management server's secret key (for the + ``file`` encryption type, that's the key stored at ``/etc/cloudstack/management/key``). + Encrypt each value with the ``EncryptionCLI`` tool that ships with CloudStack, the same + tool used to encrypt the database password (see :doc:`management`): + + .. code:: bash + + # java -classpath /usr/share/cloudstack-common/lib/cloudstack-utils.jar com.cloud.utils.crypt.EncryptionCLI -p `cat /etc/cloudstack/management/key` -i guest - Sample, with ``guest`` as values for both fields: + Take the value printed by that command and wrap it in ``ENC(...)`` in ``cred.properties``, + for both ``username`` and ``password``: .. code:: bash - username=ENC(nh2XrM7jWHMG4VQK18iiBQ==) - password=ENC(nh2XrM7jWHMG4VQK18iiBQ==) + username=ENC() + password=ENC() - ``PBEWithMD5AndDES``, used in earlier releases of this guide, is a weak algorithm and should - not be used for new deployments; ``PBEWITHHMACSHA512ANDAES_256`` above is a stronger, - future-proof alternative. Use the ``jasypt`` CLI tools (or any tool using the jasypt library) - with the same algorithm, IV generator and ``APP_ENCRYPTION_PASSWORD`` to produce the - encrypted values for ``cred.properties``. + This only works once encryption is enabled on the management server, i.e. + ``password.encryption.type`` in ``db.properties`` is set to something other than + ``none`` (see :doc:`management`). If encryption is not enabled, the ``ENC(...)`` values + are passed through undecrypted and the RabbitMQ connection will fail with a + bad-credentials error. #. Restart the Management Server.