# Crypto

These functions can be used when hashing data, encrypting data, and for securely authenticating users into the database.

These functions can be used when hashing data, encrypting data, and for securely authenticating users into the database.

<table>
  <thead>
    <tr>
      <th scope="col">Function</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptoblake3"><code>crypto::blake3()</code></a></td>
      <td scope="row" data-label="Description">Returns the blake3 hash of a value</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptojoaat"><code>crypto::joaat()</code></a></td>
      <td scope="row" data-label="Description">Returns the joaat hash of a value</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptomd5"><code>crypto::md5()</code></a></td>
      <td scope="row" data-label="Description">Returns the md5 hash of a value</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptosha1"><code>crypto::sha1()</code></a></td>
      <td scope="row" data-label="Description">Returns the sha1 hash of a value</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptosha256"><code>crypto::sha256()</code></a></td>
      <td scope="row" data-label="Description">Returns the sha256 hash of a value</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptosha512"><code>crypto::sha512()</code></a></td>
      <td scope="row" data-label="Description">Returns the sha512 hash of a value</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptoargon2compare"><code>crypto::argon2::compare()</code></a></td>
      <td scope="row" data-label="Description">Compares an argon2 hash to a password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptoargon2generate"><code>crypto::argon2::generate()</code></a></td>
      <td scope="row" data-label="Description">Generates a new argon2 hashed password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptobcryptcompare"><code>crypto::bcrypt::compare()</code></a></td>
      <td scope="row" data-label="Description">Compares an bcrypt hash to a password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptobcryptgenerate"><code>crypto::bcrypt::generate()</code></a></td>
      <td scope="row" data-label="Description">Generates a new bcrypt hashed password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptopbkdf2compare"><code>crypto::pbkdf2::compare()</code></a></td>
      <td scope="row" data-label="Description">Compares an pbkdf2 hash to a password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptopbkdf2generate"><code>crypto::pbkdf2::generate()</code></a></td>
      <td scope="row" data-label="Description">Generates a new pbkdf2 hashed password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptoscryptcompare"><code>crypto::scrypt::compare()</code></a></td>
      <td scope="row" data-label="Description">Compares an scrypt hash to a password</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#cryptoscryptgenerate"><code>crypto::scrypt::generate()</code></a></td>
      <td scope="row" data-label="Description">Generates a new scrypt hashed password</td>
    </tr>
  </tbody>
</table>

## `crypto::blake3`

The `crypto::blake3` function returns the blake3 hash of the input value.

```surql title="API DEFINITION"
crypto::blake3(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::blake3("tobie");

-- '85052e9aab1b67b6622d94a08441b09fd5b7aca61ee360416d70de5da67d86ca'
```

<br />

## `crypto::joaat`

_(since v3.0.0)_

The `crypto::joaat` function returns the joaat hash of the input value.

```surql title="API DEFINITION"
crypto::joaat(string) -> number
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::joaat("tobie");

-- 2129482046
```

<br />

## `crypto::md5`

The `crypto::md5` function returns the md5 hash of the input value.

```surql title="API DEFINITION"
crypto::md5(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::md5("tobie");

-- "4768b3fc7ac751e03a614e2349abf3bf"
```

<br />

## `crypto::sha1`

The `crypto::sha1` function returns the sha1 hash of the input value.

```surql title="API DEFINITION"
crypto::sha1(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::sha1("tobie");

-- "c6be709a1b6429472e0c5745b411f1693c4717be"
```

<br />

## `crypto::sha256`

The `crypto::sha256` function returns the sha256 hash of the input value.

```surql title="API DEFINITION"
crypto::sha256(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::sha256("tobie");

-- "33fe1859daba927ea5674813adc1cf34b9e2795f2b7e91602fae19c0d0c493af"
```

<br />

## `crypto::sha512`

The `crypto::sha512` function returns the sha512 hash of the input value.

```surql title="API DEFINITION"
crypto::sha512(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::sha512("tobie");

"39f0160c946c4c53702112d6ef3eea7957ea8e1c78787a482a89f8b0a8860a20ecd543432e4a187d9fdcd1c415cf61008e51a7e8bf2f22ac77e458789c9cdccc"
```

<br />

## `crypto::argon2::compare`

The `crypto::argon2::compare` function compares a hashed-and-salted argon2 password value with an unhashed password value.

```surql title="API DEFINITION"
crypto::argon2::compare(string, $against: string) -> bool
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
LET $hash = "$argon2id$v=19$m=4096,t=3,p=1$pbZ6yJ2rPJKk4pyEMVwslQ$jHzpsiB+3S/H+kwFXEcr10vmOiDkBkydVCSMfRxV7CA";
LET $pass = "this is a strong password";
RETURN crypto::argon2::compare($hash, $pass);

-- true
```

<br />

## `crypto::argon2::generate`

The `crypto::argon2::generate` function hashes and salts a password using the argon2 hashing algorithm.

> [!IMPORTANT]
> At this time, there is no way to customise the parameters for this function. This applies to: memory, iterations and parallelism.

```surql title="API DEFINITION"
crypto::argon2::generate(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::argon2::generate("this is a strong password");

"$argon2id$v=19$m=4096,t=3,p=1$pbZ6yJ2rPJKk4pyEMVwslQ$jHzpsiB+3S/H+kwFXEcr10vmOiDkBkydVCSMfRxV7CA"
```

<br />

## `crypto::bcrypt::compare`

The `crypto::bcrypt::compare` function compares a hashed-and-salted bcrypt password value with an unhashed password value.

```surql title="API DEFINITION"
crypto::bcrypt::compare(string, $against: string) -> bool
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
LET $hash = "$2b$12$OD7hrr1Hycyk8NUwOekYY.cogCICpUnwNvDZ9NiC1qCPHzpVAQ9BO";
LET $pass = "this is a strong password";
RETURN crypto::bcrypt::compare($hash, $pass);

true
```

<br />

## `crypto::bcrypt::generate`

The `crypto::bcrypt::generate` function hashes and salts a password using the bcrypt hashing algorithm.

> [!IMPORTANT]
> At this time, there is no way to customise the work factor for bcrypt.

```surql title="API DEFINITION"
crypto::bcrypt::generate(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::bcrypt::generate("this is a strong password");

"$2b$12$OD7hrr1Hycyk8NUwOekYY.cogCICpUnwNvDZ9NiC1qCPHzpVAQ9BO"
```

<br />

## `crypto::pbkdf2::compare`

The `crypto::pbkdf2::compare` function compares a hashed-and-salted pbkdf2 password value with an unhashed password value.

```surql title="API DEFINITION"
crypto::pbkdf2::compare(string, $against: string) -> bool
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
LET $hash = "$pbkdf2-sha256$i=10000,l=32$DBURRPJODKEt0IId1Lqe+w$Ve8Z00mibHDSKLbyKTceEBBcDpGoK0AEUl7QzDTIec4";
LET $pass = "this is a strong password";
RETURN crypto::pbkdf2::compare($hash, $pass);


true
```

<br />

## `crypto::pbkdf2::generate`

The `crypto::pbkdf2::generate` function hashes and salts a password using the pbkdf2 hashing algorithm.

> [!IMPORTANT]
> At this time, there is no way to customise the number of iterations for pbkdf2.

```surql title="API DEFINITION"
crypto::pbkdf2::generate(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::pbkdf2::generate("this is a strong password");

"$pbkdf2-sha256$i=10000,l=32$DBURRPJODKEt0IId1Lqe+w$Ve8Z00mibHDSKLbyKTceEB"
```

<br />

## `crypto::scrypt::compare`

The `crypto::scrypt::compare` function compares a hashed-and-salted scrypt password value with an unhashed password value.

```surql title="API DEFINITION"
crypto::scrypt::compare(string, $against: string) -> bool
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
LET $hash = "$scrypt$ln=15,r=8,p=1$8gl7bipl0FELTy46YJOBrw$eRcS1qR22GI8VHo58WOXn9JyfDivGo5yTJFvpDyivuw";
LET $pass = "this is a strong password";
RETURN crypto::scrypt::compare($hash, $pass);


true
```

<br />

## `crypto::scrypt::generate`

The `crypto::scrypt::generate` function hashes and salts a password using the scrypt hashing algorithm.

> [!IMPORTANT]
> At this time, there is no way to customise the parameters for this function. This applies to: cost parameter, block size and parallelism.

```surql title="API DEFINITION"
crypto::scrypt::generate(string) -> string
```
The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN crypto::scrypt::generate("this is a strong password");

"$scrypt$ln=15,r=8,p=1$8gl7bipl0FELTy46YJOBrw$eRcS1qR22GI8VHo58WOXn9JyfDivGo5yTJFvpDyivuw"
```

<br /><br />