Whenever a user saves a macro expression, the system automatically adds a security signature. The signature contains the user name of the macro's author and a hash of the given expression. To improve security, the hash function used when creating macro signatures appends a salt to the input (a sequence of additional characters). The salt value depends on the configuration of the application's environment, so the signatures are in most cases not valid when deploying macros to other instances of Kentico CMS.

 

You can recognize signed macro expressions by the # character, which the system automatically inserts before the closing %} parentheses when saving the text containing the macro.

 

 

If the execution of the macro requires any permissions, the system resolves the macro only if the user specified by the signature has the appropriate permissions.

 

Permissions are only checked when resolving macro expressions that:

 

•access an InfoObject through another InfoObject (i.e. access an encapsulated object), for example: {% CurrentDocument.DocumentPageTemplate %}

•access an InfoObjectCollection, for example: {% CurrentUser.Children["cms_category"][0].CategoryName %}

 

The system carries out a security check for each access to any collection, not just for the final macro result.

 

 

Disabling the security signature for specific macros

 

If you manually add the @ character before the closing %} sequence of a macro, the system does not add a signature.

 

 

These macros do not store the user name of the author or the security hash, so the internal length of the expression does not exceed the visible number of characters. This allows you to safely use macros in fields with a limited character count.

 

Unsigned macros are always evaluated with the permissions of a public user.

 

Configuring the hash salt for macro signatures

 

The system appends a salt to the input of the hash function that creates macro signatures.

 

The default salt is the application's main database connection string (the exact CMSConnectionString value set in the web.config file). However, we strongly recommend using a custom salt.

 

A custom salt provides the following benefits:

 

•Stability (you do not need to re-sign macros if your connection string changes)

•You can use the same salt for other instances of Kentico CMS, which makes deployment easier and allows content staging of macros

 

The best option is to set the hash salt value before you start creating content for your website. Changing the salt causes all current hash values to become invalid (including macro signatures).

 

To set a custom hash salt value for your application, add the CMSHashStringSalt key to the appSettings section of your web.config file. You can use any string as the value, but the salt should be random and at least 16 characters long. For example, a randomly generated GUID is a strong salt:

 

 

 

Re-signing existing macros [Only available after applying hotfix 7.0.9 or newer]

 

If the hash salt value used by your application changes, the security signatures of existing macro expressions become invalid. This may lead to problems with unresolved macros, for example when:

 

•The connection string of your application has changed, e.g., when moving to a different server or after setting a new database password.

•You are using Content staging to transfer data containing macros to an instance of Kentico CMS with a different connection string.

•You have set a new custom salt via the CMSHashStringSalt web.config key.

 

You can repair invalid macro signatures by re-signing all macros using a new hash salt:

 

1. Go to Site Manager -> Administration -> System -> Macros.

 

2. Fill in the Old salt field.

 

•If you leave the Sign all macros option disabled, the system attempts to re-sign macros based on the data in the original signatures. As a result, only macros that have a valid signature under the old salt are re-signed and the user names of the macro authors remain unchanged. You need to enter the old salt that was used to generate the security hash of the existing macro expressions in the system.

 

oBy default, the old salt is the value of the application's previous connection string in format:
Persist Security Info=False;database=DBName;server=ServerName;user id=DBUser;password=pwd;Current Language=English;Connection Timeout=240;

 

oIf your application uses a custom hash salt, enter the original value of the CMSHashStringSalt web.config key.

 

•If you enable Sign all macros, the macro re-signing process skips the signature integrity check and creates new signatures for all macros. This includes macros that are unsigned or have invalid signatures. The new signatures use the name of the user who started the re-signing procedure. You do not need to enter the old salt value in this case.

 

3. Type in the New salt that will be used to re-sign the macros.

oBy default, the field automatically loads the current application's hash salt value. To enter a different value, disable the Use current salt option.

 

 

4. Click Update macro signatures.

 

The system replaces the security signature in all occurrences of macros based on the new salt.