> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# $wsSecurity - Encryption

> Reference for $wsSecurity: encrypt, decrypt and hash sensitive data like passwords or tokens directly inside WEBSALE templates for safe handling.

With the `$wsSecurity` module, you can encrypt, decrypt, and hash data. It is used to protect sensitive data such as passwords, tokens, or personal information. In this section, you will learn how to use the various encryption and hash methods.

***

## Module overview

**Example / excerpt of** `$wsSecurity`

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{= $wsSecurity | json }}
```

**JSON output**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "decrypt": "ƒ()",
  "encrypt": "ƒ()",
  "encryptManual": "ƒ()",
  "hash": "ƒ()"
}
```

Note: `ƒ()` denotes a function.

**Methods overview**

| **Method**        | **Return type** | **Description**                                                                        |
| ----------------- | --------------- | -------------------------------------------------------------------------------------- |
| `decrypt()`       | string          | Decrypts data that was encrypted with `encrypt()`.                                     |
| `encrypt()`       | string          | Encrypts data with an encryption method defined in the shop configuration.             |
| `encryptManual()` | map             | Encrypts data like `encrypt()`, but returns only the individual components separately. |
| `hash()`          | string          | Calculates a cryptographic hash value of the input data.                               |

***

## Templates

The security functions can be used in any template, typically for:

* Forms with sensitive data
* Token generation for links
* Password processing in the registration process
* Data transfer to external systems

***

## Variables

No variables are available for `$wsSecurity`.

***

## Methods

### \$wsSecurity.decrypt()

Decrypts data that was encrypted with `$wsSecurity.encrypt()`.

**Signature**\
`$wsSecurity.decrypt(data)`

**Return value**\
`string` - Decrypted data in plain text.

**Parameters**

| **Name** | **Type** | **Required** | **Description**                   |
| -------- | -------- | ------------ | --------------------------------- |
| `data`   | string   | yes          | Encrypted data in WEBSALE format. |

**Example** that decrypts encrypted data.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myDecryptedData = $wsSecurity.decrypt($encryptedData) }}
```

### \$wsSecurity.encrypt()

Encrypts data with an encryption method defined in the shop configuration. The encrypted data can only be decrypted again with `decrypt()`.

**Signature**\
`$wsSecurity.encrypt(id, data, encryptionMethod, encoding)`

**Return value**\
`string` - Encrypted data in WEBSALE format.

**Parameters**

| **Name**           | **Type** | **Required** | **Description**                                                                                                                                                                                                                                              |
| ------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | string   | yes          | ID of the configured encryption method from [security - Security rules](/en/konfiguration/security-sicherheitsregeln).                                                                                                                                       |
| `data`             | string   | yes          | Data to be encrypted.                                                                                                                                                                                                                                        |
| `encryptionMethod` | string   | yes          | Encryption method.   <br />Possible values:  <br />- `blowfish` - Blowfish block cipher in ECB mode. <br />- `aescbc` - AES block cipher in CBC mode. <br />- `aesgcm` - AES block cipher in GCM mode. <br />- `tdes` - Triple DES block cipher in CBC mode. |
| `encoding`         | string   | yes          | Output encoding: `hex` or `base64`.                                                                                                                                                                                                                          |

**Example** that encrypts data with AES-GCM.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myEncryptedData = $wsSecurity.encrypt("token_v1", "Sensitive data", "aesgcm", "base64") }}
```

### \$wsSecurity.encryptManual()

Encrypts data like `encrypt()`, but returns the individual components (ciphertext, salt, auth tag) separately. Useful for integration with external systems that expect a different format.

**Signature**\
`$wsSecurity.encryptManual(id, data, encryptionMethod, encoding)`

**Return value**\
`map` - Map with the individual encryption parts.

**Return fields**

| **Return value** | **Type** | **Description**                                         |
| ---------------- | -------- | ------------------------------------------------------- |
| `ciphertext`     | string   | Encrypted data.                                         |
| `keySalt`        | string   | Key for deriving the salt.                              |
| `tag`            | string   | Auth token for authenticity check (only with `aesgcm`). |

**Parameters**

| **Name**           | **Type** | **Required** | **Description**                                                                                                                                                                                                                                              |
| ------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | string   | yes          | ID of the encryption configuration from `security.method.encrypt`.                                                                                                                                                                                           |
| `data`             | string   | yes          | Data to be encrypted.                                                                                                                                                                                                                                        |
| `encryptionMethod` | string   | yes          | Encryption method.   <br />Possible values:  <br />- `blowfish` - Blowfish block cipher in ECB mode. <br />- `aescbc` - AES block cipher in CBC mode. <br />- `aesgcm` - AES block cipher in GCM mode. <br />- `tdes` - Triple DES block cipher in CBC mode. |
| `encoding`         | string   | yes          | Output encoding: `hex` or `base64`.                                                                                                                                                                                                                          |

Example that encrypts data and uses the parts individually:

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myResult = $wsSecurity.encryptManual("token_v1", "Sensitive data", "aesgcm", "hex") }}
Ciphertext: {{= $myResult.ciphertext }}
Salt: {{= $myResult.keySalt }}
Tag: {{= $myResult.tag }}
```

### \$wsSecurity.hash()

Calculates a cryptographic hash value of the input data. Hash values are one-way encryptions – they cannot be converted back to the original data. Typical use case: password storage.

**Signature**\
`$wsSecurity.hash(id, data, hashingMethod, encoding)`

**Return value**\
`string` - Hash value of the data.

**Parameters**

| **Name**        | **Type** | **Required** | **Description**                                           |
| --------------- | -------- | ------------ | --------------------------------------------------------- |
| `id`            | string   | yes          | ID of the hash configuration from `security.method.hash`. |
| `data`          | string   | yes          | Data to be hashed.                                        |
| `hashingMethod` | string   | yes          | Hash method: `sha256` or `sha512`.                        |
| `encoding`      | string   | yes          | Output encoding: `hex` or `base64`.                       |

**Example** that hashes a password with a configured method.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $myHashedPassword = $wsSecurity.hash("password_v1", $userPassword) }}
```

***

## Actions

No actions are available for `$wsSecurity`. Encryption and hashing are performed directly through the module's methods.

***

## Examples

In this example, sensitive data is encrypted and later decrypted again.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $encrypted = $wsSecurity.encrypt("token_v1", "Secret message", "aesgcm", "base64") }}

{{ var $decrypted = $wsSecurity.decrypt($encrypted) }}
```

### Hash a password

In this example, a password is hashed. The hash value can later be compared with a re-hashed password.

```html theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{{ var $hashedPassword = $wsSecurity.hash("password_v1", $password, "sha256", "hex") }}
```

***

## Related links

* [security - Security rules](/en/konfiguration/security-sicherheitsregeln)