# Security in Secrets

Who may do what (IAM), what is recorded, and how a secret is protected.

## IAM actions

Secrets is regionless. A secret's resource name is `rn:ews::<org>:secrets:secret/<id>`, a source's
`rn:ews::<org>:secrets:source/<id>`, an environment's `rn:ews::<org>:secrets:environment/<id>`.
Actions on one secret are checked against that secret's resource name, so a policy can name one
secret; list and create actions are checked on the service.

(The table of IAM actions is generated on the web page.)
- **`secrets:GetSecretValue`** is the one action that hands over a value. It is sensitive: the
  generated read-only policies leave it out, and refusals are recorded in the audit log.
- **`secrets:CompareSecretValues`** says whether two values are equal, never what they are. It is
  sensitive too.
- **Rotating, rolling back, granting and revoking** each have their own action, separate from
  `secrets:UpdateSecret` (description, group, rotation interval).
- **`secrets:UseSecretSource`** is needed to make the platform resolve a reference through a source,
  separately from `secrets:CreateSecret`: a source's credential usually sees far more than one app
  needs.
- A grant is necessary, not sufficient: for a workflow, the person who started the run also needs
  `secrets:GetSecretValue` on the secret.
- Setting an app's secrets environment needs `deploy:UpdateApp`; the app flow needs
  `deploy:DescribeApp`.

In the console, most controls you may not use stay visible and say which action they need. Some
do not: the actions on a source's row (**Sync now**, **Test connection**, **Rename**, **Replace
token**, **Disconnect**) are refused only when you use them, and without
`secrets:ListSecretSources` or `secrets:ListSecretEnvironments` the **Sources** or
**Environments** page shows only that your policies do not grant it.

## Audit

Every write is recorded in the audit log with its outcome, and so are reads of a value and value
comparisons, allowed or refused (a matrix or diff records one refused comparison per request).
Reading a secret's access log (`secrets:GetSecretAccessLog`) is recorded only when refused. Separately, each secret's access log
records every read of its value: who or what, which version, when. See
[See who has read a secret](see-who-has-read-a-secret.md).

## Encryption

Values are encrypted with AES-256-GCM under your KMS key, and every version is kept encrypted. See
[Keys and encryption](keys-and-encryption.md). No list, describe, flow, matrix or log response
contains a value, and sync errors carry the reference and the provider's error, never a value.

## Related

- [What runs where](what-runs-where.md)
