Add docs for password policies

website/data/api-navigation.js

@@ -124,6 +124,7 @@ export default [
       'plugins-catalog',
       'policy',
       'policies',
+      'policies-password',
       'pprof',
       'raw',
       'rekey',

website/data/docs-navigation.js

@@ -33,6 +33,7 @@ export default [
       'tokens',
       'response-wrapping',
       'policies',
+      'password-policies',
       'ha',
       'integrated-storage',
       'pgp-gpg-keybase',

website/pages/api-docs/system/policies-password.mdx

@@ -0,0 +1,157 @@
+---
+layout: api
+page_title: /sys/policies/password - HTTP API
+sidebar_title: <code>/sys/policies/password</code>
+description: >-
+  The `/sys/policies/password` endpoints are used to manage password generation policies in Vault.
+---
+
+# `/sys/policies/password/`
+
+The `/sys/policies/password/` endpoints are used to manage password generation policies in Vault.
+Not all secret engines utilize password policies, so check the documentation for the engine you
+are using for compatibility.
+
+~> Password policies are only available in Vault version 1.5+.
+
+See [Password Policies](/docs/concepts/password-policies) for details of how password policies work
+as well as the syntax of the policies themselves.
+
+## Create/Update Password Policy
+
+This endpoint adds a new or updates an existing password policy. Once a policy is updated,
+it takes effect immediately to all associated secret engines.
+
+Prior to Vault saving the password policy, it will attempt to generate a number of passwords
+from the policy. This helps prevent creating password policies that are impossible to satisfy
+as well as prevent password policies that are overly restrictive which prevents both a poor
+security posture for the policy as well as preventing performance problems due to slow
+generation times.
+
+| Method | Path                           |
+| :----- | :----------------------------- |
+| `PUT`  | `/sys/policies/password/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the password policy to create.
+  This is specified as part of the request URL.
+
+- `policy` `(string: <required>)` - Specifies the password policy document. This can be
+  base64-encoded to avoid string escaping. See [Password Policy Syntax](#password-policy-syntax)
+  for details on password policy definitions.
+
+### Sample Payload
+
+```json
+{
+  "policy": "length = 20\nrule \"charset\" { ..."
+}
+```
+
+### Sample Request
+**cURL:**
+```shell
+$ cat payload.json
+{
+  "policy": "length = 20\nrule \"charset\" {\n  charset = \"abcde\"\n}\n"
+}
+
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request PUT \
+    --data @payload.json \
+    http://127.0.0.1:8200/v1/sys/policies/password/my-policy
+```
+
+**Vault CLI:**
+```shell
+$ cat my-policy.hcl
+length = 20
+rule "charset" {
+    charset = "abcde"
+}
+
+$ vault write sys/policies/password/my-policy policy=@my-policy.hcl
+```
+
+## Read Password Policy
+
+This endpoint retrieves information about the named password policy.
+
+| Method | Path                           |
+| :----- | :----------------------------- |
+| `GET`  | `/sys/policies/password/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the password policy to retrieve.
+  This is specified as part of the request URL.
+
+### Sample Request
+
+```shell
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/sys/policies/password/my-policy
+```
+
+### Sample Response
+```json
+{
+  "policy": "length = 20\nrule \"charset\" { ..."
+}
+```
+
+## Delete Password Policy
+
+This endpoint deletes the password policy with the given name. This does not check if any
+secret engines are using it prior to deletion, so you should ensure that any engines that
+are utilizing this password policy are changed to a different policy (or to that engines'
+default behavior).
+
+| Method | Path                           |
+| :----- | :----------------------------- |
+| `DELETE`  | `/sys/policies/password/:name` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the password policy to delete.
+  This is specified as part of the request URL.
+
+### Sample Request
+
+```shell
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request DELETE
+    http://127.0.0.1:8200/v1/sys/policies/password/my-policy
+```
+
+## Generate Password from Password Policy
+
+This endpoint generates a password from the specified existing password policy.
+
+| Method | Path                           |
+| :----- | :----------------------------- |
+| `GET`  | `/sys/policies/password/:name/generate` |
+
+### Parameters
+
+- `name` `(string: <required>)` – Specifies the name of the password policy to generate
+  a password from. This is specified as part of the request URL.
+
+### Sample Request
+
+```shell
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/sys/policies/password/my-policy/generate
+```
+
+### Sample Response
+```json
+{
+  "password": "..."
+}
+```