<!-- review: finished -->

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

# Secure Link

该模块用于检查请求链接的真实性，保护资源免受未经授权的访问，并限制链接的生命周期。

请求链接的真实性通过比较请求中传递的校验和值和为请求计算的值来验证。如果链接有有限的生命周期且时间已过期，则该链接被视为过时。这些检查的状态在 [$secure_link](#v-secure-link) 变量中可用。

该模块提供两种替代操作模式。第一种模式通过 [secure_link_secret](#secure-link-secret) 指令启用，用于检查请求链接的真实性以及保护资源免受未经授权的访问。第二种模式通过 [secure_link](#id2) 和 [secure_link_md5](#secure-link-md5) 指令启用，也用于限制链接的生命周期。

当 [从源代码构建](https://cn.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) 时，此模块默认不构建；应使用 `--with-http_secure_link_module` [构建选项](https://cn.angie.software//angie/docs/installation/sourcebuild.md#configure) 启用。

在来自 [我们的仓库](https://cn.angie.software//angie/docs/installation/index.md#install-packages) 的软件包和镜像中，模块包含在构建中。

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

## 指令

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

<a id="id2"></a>

### secure_link

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link` 表达式;     |
|--------------------------------------------------------------------------------------|------------------------|
| 默认值                                                                                  | —                      |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location |

定义一个包含变量的字符串，用于从中提取链接的校验和值和生命周期。

表达式中使用的变量通常与请求相关联；请参阅下面的 [示例](#secure-link-md5)。

从字符串中提取的校验和值与由 [secure_link_md5](#secure-link-md5) 指令定义的表达式的 MD5 哈希值进行比较。

如果校验和不匹配，则 [$secure_link](#v-secure-link) 变量被设置为空字符串。如果校验和匹配，则检查链接的生命周期。

如果链接有有限的生命周期且时间已过期，则 [$secure_link](#v-secure-link) 变量被设置为 `0`。否则，它被设置为 `1`。请求中传递的 MD5 哈希值以 base64url 编码。

如果链接有有限的生命周期，则过期时间以自纪元（1970年1月1日 00:00:00 GMT）以来的秒数设置。该值在表达式中指定于 MD5 哈希之后，并以逗号分隔。请求中传递的过期时间可通过 [$secure_link_expires](#v-secure-link-expires) 变量用于 [secure_link_md5](#secure-link-md5) 指令。如果未指定过期时间，则链接具有无限的生命周期。

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

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

### secure_link_md5

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link_md5` 表达式;   |
|--------------------------------------------------------------------------------------|--------------------------|
| 默认值                                                                                  | —                        |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location   |

定义一个表达式，其 MD5 哈希值将被计算并与请求中传递的值进行比较。

表达式应包含链接（资源）的受保护部分和一个秘密成分。如果链接有有限的生命周期，表达式还应包含 [$secure_link_expires](#v-secure-link-expires)。

为了防止未经授权的访问，表达式可以包含一些关于客户端的信息，例如其地址和浏览器版本。

示例：

```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;
    }

#    ...
}
```

链接 "/s/link?md5=_e4Nc3iduzkWRm01TBBNYw&expires=2147483647" 限制了对客户端 IP 地址为 127.0.0.1 的 "/s/link" 的访问。该链接也有限的生命周期，直到 2038 年 1 月 19 日（GMT）。

在 UNIX 上，可以通过以下命令获取 md5 请求参数值：

```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

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `secure_link_secret` 单词;   |
|--------------------------------------------------------------------------------------|----------------------------|
| 默认值                                                                                  | —                          |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | location                   |

定义一个秘密单词，用于检查请求链接的真实性。

请求链接的完整 URI 如下所示：

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

其中 hash 是为链接和秘密单词连接而计算的 MD5 哈希的十六进制表示，prefix 是没有斜杠的任意字符串。

如果请求链接通过了真实性检查，则 [$secure_link](#v-secure-link) 变量被设置为从请求 URI 提取的链接。否则，[$secure_link](#v-secure-link) 变量被设置为空字符串。

示例：

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

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

    rewrite ^ /secure/$secure_link;
}

location /secure/ {
    internal;
}
```

请求 "/p/5e814704a28d9bc1914ff19fa0c4a00a/link" 将被内部重定向到 "/secure/link"。

在 UNIX 上，可以通过以下命令获取此示例的哈希值：

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

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

## 内置变量

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

### `$secure_link`

链接检查的状态。具体值取决于所选的操作模式。

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

### `$secure_link_expires`

在请求中传递的链接的生命周期；仅用于 [secure_link_md5](#secure-link-md5) 指令。