---
title: Macros and security
related:
  - https://docs.kentico.com/13/macro-expressions.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Macros are an essential part of Xperience. You can read more about them in the [Macro expressions](https://docs.kentico.com/13/macro-expressions.md) chapter. This page focuses on the security mechanisms and best practices related to macros.

## Signing macros

Whenever a user saves a complex macro expression, the system automatically adds a security signature. This signature contains an **identifier** of the macro's author (the user name or an assigned macro identity) and a **hash** of the given expression.

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:

- _{%CurrentSite.SiteID #%}_

For illustration, a signed macro may look like this in the database:

- _{%CurrentSite.SiteID|(user)administrator|(hash)9056b7b76629a47a660c40cc2e5b0d92a13d0f9bce178847ca412c3a585552a1%}_
- _{%CurrentSite.SiteID|(identity)GlobalAdministrator|(hash)e3402fe14374ab15d119dddbb6c831ce3d2ef55bd8e70ce8eb80994f4e6ad18b%}_

> **Info:** Hashing is omitted when submitting very simple macros (e.g., {%FullName%}). Macros are signed only when they contain an indexer or a dot.

The system checks the macro signature when accessing an object through a different object (for example the user settings of a user object) and evaluates whether the user (identified by the signature) has **permissions** to execute the macro.

The best practice is to use the least privilege approach – submit macros signed by a user who has access only to the required objects and nothing else.

## SQL injections

Macros can become part of SQL queries, for example in _WhereCondition_ and _OrderBy_ fields, which can lead to SQL injection vulnerability.

To protect from SQL injection, we recommend using the SQLEscape method when handling SQL macros:

```sql

WHERE UserName LIKE '%{% SQLEscape(QueryString.GetValue("test", ""))#%}%'

```

However, if you expect a different data type than string (for example an integer), you need to convert the macro to the correct data type. The SQLEscape method is useless in this case.

```sql

WHERE UserID = {% ToInt(QueryString.GetValue("test", ""), 0)#%}

```

## Output encoding of macros

Macro encoding is an essential protection against XSS. You must encode output macros properly, unless you want to display some HTML code using the particular macro. There are several methods for encoding macros in Xperience:

- {% UrlEncode(CurrentUser.FullName) %} – macro is encoded into the query URL.
- {% HTMLEncode(CurrentUser.FullName) %} – macro is a part of standard page output text and text between HTML tags.
- {% HTMLAttributeEncode(CurrentUser.FullName) %} – macro is a part of an HTML attribute
- {% JSEscape(CurrentUser.FullName) %} – macro is a part of JS code.

## Writing custom macro methods

When creating a [custom macro method](https://docs.kentico.com/13/macro-expressions/extending-the-macro-engine/registering-custom-macro-methods.md), you need to ensure security yourself. The macro engine cannot predict which data is accessed in the method, and thus cannot properly secure the method.

## Unsafe macros

Query macros, cookie macros and data macros (information from the database, e.g. user display name) and their equivalent properties can be potentially dangerous. When you use these macros, you have to secure them against SQL injection and XSS.

> **Note:** It is NOT possible to gain access to user passwords using macros.