<!-- review: finished -->

<a id="http-secure-link"></a>

# Secure Link

The module allows checking authenticity of requested links, protecting resources from unauthorized access, and limiting link lifetime.

The authenticity of a requested link is verified by comparing the checksum value passed in a request with the value computed for the request. If a link has a limited lifetime and the time has expired, the link is considered outdated. The status of these checks is made available in the [$secure_link](#v-secure-link) variable.

The module implements two alternative operation modes. The first mode is enabled by the [secure_link_secret](#secure-link-secret) directive and allows checking authenticity of requested links and protecting them from unauthorized access. The second mode is enabled by the [secure_link](#id1) and [secure_link_md5](#secure-link-md5) directives and also allows limiting link lifetime.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
this module isn't built by default;
it should be enabled with the
`‑‑with‑http_secure_link_module`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).

In packages and images from [our repos](https://en.angie.software//angie/docs/installation/index.md#install-packages),
the module is included in the build.

<a id="directives-41"></a>

## Directives

<a id="index-0"></a>

<a id="id1"></a>

### secure_link

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link` expression;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | —                           |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location      |

Defines a string with variables from which the checksum value and lifetime of a link will be extracted.

Variables used in an expression are usually associated with a request; see [example](#secure-link-md5) below.

The checksum value extracted from the string is compared with the MD5 hash value of the expression defined by the [secure_link_md5](#secure-link-md5) directive.

If the checksums do not match, the [$secure_link](#v-secure-link) variable is set to an empty string. If the checksums match, the link lifetime is checked.

If the link has a limited lifetime and the time has expired, the [$secure_link](#v-secure-link) variable is set to `0`. Otherwise, it is set to `1`. The MD5 hash value passed in a request is encoded in base64url.

If a link has a limited lifetime, the expiration time is set in seconds since Epoch (January 1, 1970 00:00:00 GMT). The value is specified in the expression after the MD5 hash, and is separated by a comma. The expiration time passed in a request is available through the [$secure_link_expires](#v-secure-link-expires) variable for use in the [secure_link_md5](#secure-link-md5) directive. If the expiration time is not specified, a link has unlimited lifetime.

<a id="index-1"></a>

<a id="secure-link-md5"></a>

### secure_link_md5

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link_md5` expression;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| Default                                                                                  | —                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location          |

Defines an expression for which the MD5 hash value will be computed and compared with the value passed in a request.

The expression should contain the secured part of a link (resource) and a secret ingredient. If the link has a limited lifetime, the expression should also contain [$secure_link_expires](#v-secure-link-expires).

To prevent unauthorized access, the expression may contain some information about the client, such as its address and browser version.

Example:

```nginx
location /s/ {
    secure_link $arg_md5,$arg_expires;
    secure_link_md5 "$secure_link_expires$uri$remote_addr secret";

    if ($secure_link = "") {
        return 403;
    }

    if ($secure_link = "0") {
        return 410;
    }

#    ...
}
```

The "/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647" link restricts access to "/s/link" for the client with the IP address 127.0.0.1. The link also has limited lifetime until January 19, 2038 (GMT).

On UNIX, the md5 request argument value can be obtained as:

```console
echo -n '2147483647/s/link127.0.0.1 secret' | \
   openssl md5 -binary | openssl base64 | tr +/ -_ | tr -d =
```

<a id="index-2"></a>

<a id="secure-link-secret"></a>

### secure_link_secret

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link_secret` word;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | —                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                     |

Defines a secret word used to check authenticity of requested links.

The full URI of a requested link looks as follows:

```console
/prefix/hash/link
```

where hash is a hexadecimal representation of the MD5 hash computed for the concatenation of the link and secret word, and prefix is an arbitrary string without slashes.

If the requested link passes the authenticity check, the [$secure_link](#v-secure-link) variable is set to the link extracted from the request URI. Otherwise, the [$secure_link](#v-secure-link) variable is set to an empty string.

Example:

```nginx
location /p/ {
    secure_link_secret secret;

    if ($secure_link = "") {
        return 403;
    }

    rewrite ^ /secure/$secure_link;
}

location /secure/ {
    internal;
}
```

A request of "/p/5e814704a28d9bc1914ff19fa0c4a00a/link" will be internally redirected to "/secure/link".

On UNIX, the hash value for this example can be obtained as:

```console
echo -n 'linksecret' | openssl md5 -hex
```

<a id="built-in-variables-9"></a>

## Built-in Variables

<a id="v-secure-link"></a>

### `$secure_link`

The status of a link check. The specific value depends on the selected operation mode.

<a id="v-secure-link-expires"></a>

### `$secure_link_expires`

The lifetime of a link passed in a request; intended to be used only in the [secure_link_md5](#secure-link-md5) directive.