HDDS-13454. Add user documentation for ozone s3 setsecret.

docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md

@@ -107,9 +107,17 @@ awsSecret=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
 ```
 
 :::note
-Starting in Ozone 1.4.0, the secret will be **shown only once** when generated with `getsecret`. If the secret is lost, the user would have to `revokesecret` first before regenerating a new secret with `getsecret`.
+Starting in Ozone 1.4.0, the secret will be **shown only once** when generated with `getsecret`. If the secret is lost, use `revokesecret` and then `getsecret` to generate a new auto-generated secret, or use `setsecret` to assign a new known value while you still have Kerberos access.
 :::
 
+To change an existing secret to a specific value, use `ozone s3 setsecret`:
+
+```bash
+ozone s3 setsecret --secret 'my-new-secret-key'
+awsAccessKey=testuser/scm@EXAMPLE.COM
+awsSecret=my-new-secret-key
+```
+
 Now, you can use the key and the secret to access the S3 endpoint:
 
 ```bash
@@ -126,7 +134,7 @@ Enter 'y' to confirm S3 secret revocation for 'testuser/scm@EXAMPLE.COM': y
 S3 secret revoked.
 ```
 
-Ozone Manager administrators can run `ozone s3 getsecret` and `ozone s3 revokesecret` command with `-u` parameter to specify another users.
+Ozone Manager administrators can run `ozone s3 getsecret`, `ozone s3 setsecret`, and `ozone s3 revokesecret` with the `-u` parameter to specify another user.
 
 ```bash
 # Obtained Kerberos TGT for testuser/scm@EXAMPLE.COM with kinit,
@@ -135,6 +143,10 @@ ozone s3 getsecret -u om/om@EXAMPLE.COM
 awsAccessKey=om/om@EXAMPLE.COM
 awsSecret=1e9379d0424cce6669b1a501ff14834e46dee004ee868b41a313b49eabcfb68f
 
+ozone s3 setsecret -u om/om@EXAMPLE.COM --secret 'admin-chosen-secret'
+awsAccessKey=om/om@EXAMPLE.COM
+awsSecret=admin-chosen-secret
+
 ozone s3 revokesecret -u om/om@EXAMPLE.COM -y
 S3 secret revoked.
 ```

docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md

@@ -68,6 +68,69 @@ aws configure set region us-west-1
 Please refer to AWS S3 documentation on how to use S3 via command line or via
 S3 API.
 
+## Set Secret
+
+Use `ozone s3 setsecret` to change an existing S3 secret to a specific value.
+Unlike `getsecret`, which auto-generates a secret when one does not exist,
+`setsecret` only updates an existing secret and requires you to provide the new
+secret key.
+
+| Command | Purpose |
+| ------- | ------- |
+| `ozone s3 getsecret` | Create or retrieve the initial auto-generated secret |
+| `ozone s3 setsecret` | Update an existing secret to a user-chosen value |
+| `ozone s3 revokesecret` | Invalidate the current secret |
+
+### Using the command line
+
+For a regular user to set their own secret:
+
+```bash
+ozone s3 setsecret --secret '<SECRET_KEY>'
+```
+
+An Ozone administrator can set a secret for a specific user by using the `-u` flag:
+
+```bash
+ozone s3 setsecret -u <username> --secret '<SECRET_KEY>'
+```
+
+The command also accepts the alias `set-secret` and the short form `-s` for
+`--secret`:
+
+```bash
+ozone s3 set-secret -s '<SECRET_KEY>'
+```
+
+To print shell `export` statements for use with `eval`:
+
+```bash
+eval $(ozone s3 setsecret -e --secret '<SECRET_KEY>')
+```
+
+Example:
+
+```bash
+kinit -kt /etc/security/keytabs/testuser.keytab testuser/scm@EXAMPLE.COM
+ozone s3 setsecret --secret 'my-new-secret-key'
+awsAccessKey=testuser/scm@EXAMPLE.COM
+awsSecret=my-new-secret-key
+```
+
+The AWS access key ID stays the same; only the secret changes. Secret keys
+must be at least 8 characters long. If no secret exists yet, run
+`ozone s3 getsecret` first.
+
+:::caution
+After `setsecret`, clients still using the old secret can no longer
+authenticate. Update `aws configure`, environment variables, or other client
+configuration with the new secret.
+:::
+
+For S3 multi-tenancy access IDs, use
+[`ozone tenant user setsecret`](../../../administrator-guide/operations/s3-multi-tenancy/tenant-commands#set-tenant-user-secret-key)
+instead.
+
 ## Revoking Secrets via REST API
 
 To invalidate/revoke the secret, use `ozone s3 revokesecret` command.

docs/04-user-guide/01-client-interfaces/04-s3a.md

@@ -87,7 +87,7 @@ Ozone S3 Gateway adds ETag support for S3 Multipart Upload (MPU). Object version
 Ozone uses the same AWS-style access key and secret key model for the S3 Gateway.
 
 - If **security is disabled**, any `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` pair can be used.
-- If **security is enabled**, obtain a key and secret via `ozone s3 getsecret` (Kerberos authentication is required). See the [S3 Protocol — Security](./s3/s3-api#security) and [Securing S3](./s3/securing-s3) sections for details.
+- If **security is enabled**, obtain a key and secret via `ozone s3 getsecret` (Kerberos authentication is required). To rotate an existing secret, use `ozone s3 setsecret`. See the [S3 Protocol — Security](./s3/s3-api#security) and [Securing S3](./s3/securing-s3#set-secret) sections for details.
 
 Configure S3A credentials in `core-site.xml`: