Azure-docs: Secrets as octet sequences

[nickwalkmsft]

Why does the "Working with secrets" section describe secrets as octet sequences? Secret values in the API are strings. The only client I've seen with direct support for anything else is the CLI, and it supports arbitrary data by using base64 or hex encoding.

The first paragraph also describes secrets as "limited size octet objects".

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 962e9ebe-e97f-7a56-03a4-33662454bdfe
• Version Independent ID: 7fda1b8c-67e2-a304-1f17-bfd5a0422766
• Content: About keys, secrets and certificates
• Content Source: articles/key-vault/about-keys-secrets-and-certificates.md
• Service: key-vault
• GitHub Login: @lleonard-msft
• Microsoft Alias: alleonar

[SaurabhSharma-MSFT]

@nickwalkmsft Thanks for your feedback! We will investigate and update as appropriate.

[SaurabhSharma-MSFT]

@nickwalkmsft I believe it is mentioned as octet sequences as any type of data is accepted and stored securely without any semantics.

[nickwalkmsft]

Thanks for getting back!

My feedback on this description is that it's not very helpful to someone using the API. Services that accept and return an unvalidated JSON string value don't typically describe the data as an octet sequence if the user is responsible for choosing a serialization format, implementing a way of specifying it, and performing the serialization/deserialization themselves if they want to store binary data.

Additionally, the primary use cases and virtually every example in the documentation uses secrets to store plaintext strings. This makes the description of secret values as octet sequences confusing.

[SaurabhSharma-MSFT]

@nickwalkmsft Thanks for you valuable inputs ! I have assigned this issue to content author to investigate and update the document as appropriate.

[BryanLa]

Hi @nickwalkmsft - thanks very much for this feedback, and apologies for the delay in getting back to you.

I would tend to agree with you, that the "octet" term doesn't add a lot of value, and as you said, might even be confusing to some folks. As such, I'm going to propose the following changes:

• in the intro paragraph of About keys, secrets, and certificates, the 2nd "Secrets" bullet:

  • change the first sentence to Provides secure storage of secrets, such as passwords and database connection strings.
  • remove the 2nd sentence: Secrets are limited size octet objects with no specific semantics.

• in the Working with secrets section

  • change the sentence: Secrets in Key Vault are octet sequences with a maximum size of 25k bytes each. , to: From a developer's perspective, Key Vault APIs accept and return secret values as strings. Internally, Key Vault stores and manages secrets as sequences of octets (8-bit bytes), with a maximum size of 25k bytes each.

These changes should be live later today. Thanks again for the feedback on this.

please-close