> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/digital-agent/tools-reference/security-and-encoding.md).

# Security & encoding

Encoding, hashing, checksums and authentication tokens.

Encoding, hashing, checksums and authentication tokens. How to add a tool and use its result is described in [Tools & smart functions](https://docs.borndigital.ai/digital-agent/tools-reference.md).

| Tool                        | Technical name           | What it does                                                                                                | Languages |
| --------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------- | --------- |
| Base64 string               | `base64_str`             | Encode or decode strings with base64 and return a string.                                                   | any       |
| Checksum Validator          | `checksum_validator`     | Validate checksum of base64 body using salt; return validity and decoded data.                              | any       |
| Decode byte64               | `decode_byte64`          | Returns dictionary of generated filename, and its respective bytes.                                         | any       |
| Encode byte64               | `encode_byte64`          | Returns b64 string.                                                                                         | any       |
| Hash string                 | `get_string_hash`        | Return hash for string input.                                                                               | any       |
| JWT client assertion        | `jwt_client_assertion`   | Build and sign a JWT client assertion for OAuth2 private\_key\_jwt client authentication.                   | any       |
| MS Graph API authentication | `msgraph_authentication` | Authenticate with Microsoft Graph API using client credentials and a certificate to obtain an access token. | any       |

## Base64 string

Technical name: `base64_str`

Encode or decode strings with base64 and return a string.

* Can also be used in expressions as `base64_str()`.

| Parameter | Name        | Required | Default  | Description                                    |
| --------- | ----------- | -------- | -------- | ---------------------------------------------- |
| Value     | `value`     | yes      |          | Plain text to encode or base64 text to decode. |
| Operation | `operation` | no       | `encode` | encode (default) or decode.                    |

**Example input:** 'value': 'test', 'operation': 'encode'

**Example output:**

```
dGVzdA==
```

## Checksum Validator

Technical name: `checksum_validator`

Validate checksum of base64 body using salt; return validity and decoded data.

| Parameter | Name   | Required | Default | Description                                                                |
| --------- | ------ | -------- | ------- | -------------------------------------------------------------------------- |
| Salt      | `salt` | yes      |         | Secret salt used to compute checksum (sha256 of body+salt).                |
| Payload   | `data` | yes      |         | JSON with keys 'body' (base64 string) and 'checkSum' (checksum to verify). |

**Example input:** salt='my\_secret', data={'body': '', 'checkSum': ''}

**Example output:**

```
{'valid': True, 'data': {'foo': 'bar'}}
```

## Decode byte64

Technical name: `decode_byte64`

Returns dictionary of generated filename, and its respective bytes.

* Can also be used in expressions as `decode_byte64()`.

| Parameter               | Name            | Required | Default | Description                                                                                              |
| ----------------------- | --------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
| List of names of images | `b64_strs_list` | yes      |         | list of names of images and its byte strings containing prefix: `data:{data_type}/{file_suffix};base64,` |

**Example input:** list of strings

**Example output:**

```
dictionary of file names as keys and bytes of image data as values
```

## Encode byte64

Technical name: `encode_byte64`

Returns b64 string.

* Can also be used in expressions as `encode_byte64()`.

| Parameter       | Name              | Required | Default | Description                   |
| --------------- | ----------------- | -------- | ------- | ----------------------------- |
| Bytes to encode | `bytes_to_encode` | yes      |         | bytes to encode to b64 format |

**Example input:** bytes to encode

**Example output:**

```
base64 string
```

## Hash string

Technical name: `get_string_hash`

Return hash for string input.

* Can also be used in expressions as `hash()`.

| Parameter     | Name            | Required | Default  | Description                                |
| ------------- | --------------- | -------- | -------- | ------------------------------------------ |
| Word          | `word`          | yes      |          | Word to use as input for hash function.    |
| Secret key    | `key`           | yes      |          | Secret key for hash function.              |
| Algorithm     | `algorithm`     | no       | `sha512` | Hash algorithm to use, default is 'sha512' |
| Base64 encode | `base64_encode` | no       | `True`   | When on, return base64 encoded hash.       |

**Example input:** 'word': 'file.ntm.45733', 'key': 'my\_super\_secret\_key'

**Example output:**

```
w6HMDAwwQS/N0be2e0pLAnASpU3O2kn0nKo4agB7cnuGFWssQ9YXYmhHe5bRYecv3mM5OB7ZUR49NKEyMQtghA==
```

## JWT client assertion

Technical name: `jwt_client_assertion`

Build and sign a JWT client assertion for OAuth2 private\_key\_jwt client authentication.

* Advanced – usually set up together with Born Digital.

| Parameter  | Name         | Required | Default | Description                                                                                                                                                   |
| ---------- | ------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JWK source | `jwk_source` | yes      |         | Path to the JWK private key file, or (temporary fallback) the JWK JSON itself (as an object or as text).                                                      |
| Client ID  | `client_id`  | yes      |         | OAuth client\_id (used as iss/sub claims).                                                                                                                    |
| Token URL  | `token_url`  | yes      |         | Token endpoint this assertion is intended for (used as aud claim), e.g. <https://idpint.tatrabanka.sk/auth/realms/int\\_realm/protocol/openid-connect/token>. |
| Scope      | `scope`      | yes      |         | Requested OAuth scope.                                                                                                                                        |
| Algorithm  | `algorithm`  | no       | `PS256` | JWT signing algorithm, must match how client\_id's key is registered on the authorization server, e.g. RS256 or PS256.                                        |

## MS Graph API authentication

Technical name: `msgraph_authentication`

Authenticate with Microsoft Graph API using client credentials and a certificate to obtain an access token.

* Advanced – usually set up together with Born Digital.

| Parameter        | Name               | Required | Default | Description                                                         |
| ---------------- | ------------------ | -------- | ------- | ------------------------------------------------------------------- |
| Client ID        | `client_id`        | yes      |         | Azure AD application (client) ID to authenticate with.              |
| Tenant ID        | `tenant_id`        | yes      |         | Azure AD directory (tenant) ID where the application is registered. |
| Certificate file | `certificate_file` | yes      |         | PEM-formatted certificate file (can be base64 encoded or data URL). |
| Private key file | `private_key_file` | yes      |         | PEM-formatted private key file (can be base64 encoded or data URL). |
| Scopes           | `scope`            | no       |         | List of permission scopes to request for the access token.          |

**Example input:** This function does not use the user input utterance.

**Example output:**

```
{'access_token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6...', 'expires_in': 3599}
```
