# Signaturen und Base64

Externe Dienste signieren ihre Anfragen oft oder erwarten eine Signatur von Ihnen und übergeben Daten in Base64. Dafür gibt es im Code drei Funktionen.

## hash_hmac

```js
hash_hmac(algo, text, key, format)
```

Berechnet eine HMAC-Signatur eines Textes mit einem geheimen Schlüssel.

| Parameter | Typ | Was übergeben wird |
|---|---|---|
| `algo` | Zeichenkette | Algorithmus: `'md5'`, `'sha1'`, `'sha256'`, `'sha512'` oder `'md4'` |
| `text` | Zeichenkette | Was signiert wird |
| `key` | Zeichenkette | Geheimer Schlüssel |
| `format` | Zeichenkette, optional | `'base64'` — Ergebnis in Base64. Ohne Parameter — hexadezimal in Kleinbuchstaben |

**Liefert** die Signatur als Zeichenkette. Ist `algo`, `text` oder `key` leer, liefert die Funktion `undefined`.

> [!WARNING]
> Übergeben Sie nur Algorithmen aus der Liste. Bei einem anderen Namen, etwa `'sha3'`, wirft die Funktion den Fehler `TypeError: hash_hmac: unsupported algorithm "sha3"…`. Fangen Sie ihn nicht mit `try...catch` ab, endet der Code mit diesem Fehler.

Signatur einer eingehenden Anfrage prüfen: Der Dienst des Ladens sendet sie im Header `X-Signature`, der geheime Schlüssel liegt in einer globalen Variablen des Bots.

```js
var secret = getGlobalVariable('shop_schluessel');
var expected = hash_hmac('sha256', request.body, secret);

if (expected !== request.headers['x-signature']) {
    throw new Error('Ungültige Signatur');
}

if (setContactById(request.data.contact_id)) {
    setContactVariable('bestellstatus', request.data.status);
}
```

Stimmt die Signatur nicht, hält der Code an, und der Block beantwortet die Anfrage mit dem Code `422`.

## base64_encode

```js
base64_encode(text)
```

Kodiert Text in Base64.

| Parameter | Typ | Was übergeben wird |
|---|---|---|
| `text` | Zeichenkette | Was kodiert wird. Umlaute und andere Sonderzeichen werden als UTF-8 kodiert |

**Liefert** eine Zeichenkette in Base64.

```js
var auth = 'Basic ' + base64_encode('flowers:secret-password');
```

## base64_decode

```js
base64_decode(text)
```

Dekodiert eine Zeichenkette aus Base64.

| Parameter | Typ | Was übergeben wird |
|---|---|---|
| `text` | Zeichenkette | Zeichenkette in Standard-Base64 |

**Liefert** den dekodierten Text oder `undefined`, wenn die Zeichenkette kein Base64 ist.

```js
var payload = base64_decode(request.data.payload);
var order = payload ? JSON.parse(payload) : null;
```