Add aka.ms links to data protection warnings

[blowdart]

When data protection starts, depending on configuration, warnings may appear.

For example, from the sample docker asp.net app we can see

warn: Microsoft.AspNetCore.DataProtection.Repositories.FileSystemXmlRepository[60]
      Storing keys in a directory '/root/.aspnet/DataProtection-Keys' that may not be persisted outside of the container. Protected data will be unavailable when container is destroyed.
warn: Microsoft.AspNetCore.DataProtection.KeyManagement.XmlKeyManager[35]
      No XML encryptor configured. Key {6a251c6c-4022-4cb3-a021-f4efd9131319} may be persisted to storage in unencrypted form.

Adding an aka.ms link to appropriate documentation pages would make these warnings more useful.

[ghost]

We've moved this issue to the Backlog milestone. This means that it is not going to be worked on for the coming release. We will reassess the backlog following the current release and consider this item at that time. To learn more about our issue management process and to have better expectation regarding different types of issues you can read our Triage Process.

[ghost]

Thanks for contacting us. We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We will evaluate the request when we are planning the work for the next milestone. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[adityamandaleeka]

Moving to 6.0. The links now exist. Just need to make them actually point to a doc.

[adityamandaleeka]

@blowdart Is this still on track for 6.0?

[adityamandaleeka]

@blowdart Bringing this to your attention since it looks like this hasn't happened yet.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s). If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s). If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[halter73]

We started logging http://aka.ms/dataprotectionwarning in .NET 6 (#36292), but it currently just links to https://github.com/dotnet/aspnetcore.

@blowdart Would https://learn.microsoft.com/aspnet/core/security/data-protection/configuration/overview or something else be better?

[blowdart]

The idea was to end up linking to some debugging/extra help pages, where each error message would have a set of steps to try. That hasn't been written yet, so I'm not sure which is better here.

[amcasey]

It looks like we use this link in a dozen or so unrelated warning strings, so the guidance will need to be fairly general. Troubleshooting steps would be great, but they'd need to be tailored to individual scenarios.

Some of them don't obviously require additional details. For example, I don't actually know what "default key lifetime" changes, but it seems fairly intuitive to me that it would have to be non-negative. I'm not sure what troubleshooting steps you could provide to someone who (accidentally?) passed a negative value.

[amcasey]

Here are the resources strings that contain the URL and some thoughts on what each requires:

Never produced

• Storing keys in a directory '{path}' that may not be persisted outside of the container. Protected data will be unavailable when container is destroyed. For more information go to http://aka.ms/dataprotectionwarning
  • The resources string is never used, but there's a related logging message
• Decrypting EncryptedXml-encapsulated payloads is not yet supported on Core CLR. For more information go to http://aka.ms/dataprotectionwarning
  • Presumably, this is simply no longer true

Too broad for a single explanation

• The provided payload could not be decrypted. Refer to the inner exception for more information. For more information go to http://aka.ms/dataprotectionwarning
• An error occurred while trying to encrypt the provided data. Refer to the inner exception for more information. For more information go to http://aka.ms/dataprotectionwarning
• An error occurred during a cryptographic operation. For more information go to http://aka.ms/dataprotectionwarning

Sufficiently explained already

• The provided payload cannot be decrypted because it was protected with a newer version of the protection provider. For more information go to http://aka.ms/dataprotectionwarning
  • The only supported version is 0, so there's not much to explain
• Property {0} must have a non-negative value. For more information go to http://aka.ms/dataprotectionwarning
  • Seems self-evident that a timeout would have to be non-negative. I guess we could say something about how to indicate an infinite timeout?
• {0} must not be negative. For more information go to http://aka.ms/dataprotectionwarning
  • Seems self-evident that a timeout would have to be non-negative. I guess we could say something about how to indicate an infinite timeout?
• The symmetric algorithm block size of {0} bits is invalid. The block size must be between 64 and 2048 bits, inclusive, and it must be a multiple of 8 bits. For more information go to http://aka.ms/dataprotectionwarning
  • This error message is already pretty explicit
• The validation algorithm digest size of {0} bits is invalid. The digest size must be between 128 and 2048 bits, inclusive, and it must be a multiple of 8 bits. For more information go to http://aka.ms/dataprotectionwarning
  • This error message is already pretty explicit
• The symmetric algorithm key size of {0} bits is invalid. The key size must be between 128 and 2048 bits, inclusive, and it must be a multiple of 8 bits. For more information go to http://aka.ms/dataprotectionwarning
  • This error message is already pretty explicit
• The payload expired at {0}. For more information go to http://aka.ms/dataprotectionwarning
  • This already includes the problem and the problematic value

Could be enhanced inline

• The provided buffer is of length {0} byte(s). It must instead be exactly {1} byte(s) in length. For more information go to http://aka.ms/dataprotectionwarning
  • Maybe add a couple words about why it's important for the length to be exact?

Could use docs

• The key {0:B} has been revoked. For more information go to http://aka.ms/dataprotectionwarning
  • Apparently revocation errors can be ignored, so we could explain the consequences of doing so
• The new key lifetime must be at least one week. For more information go to http://aka.ms/dataprotectionwarning
  • Wouldn't hurt to explain this requirement
• GCM algorithms require the Windows platform. For more information go to http://aka.ms/dataprotectionwarning
  • Maybe we could link to a page about GCM?
• A certificate with the thumbprint '{0}' could not be found. For more information go to http://aka.ms/dataprotectionwarning
  • I guess we could explain how to enumerate available certs?
• The key ring does not contain a valid default protection key. The data protection system cannot create a new key because auto-generation of keys is disabled. For more information go to http://aka.ms/dataprotectionwarning
  • I guess we could talk about why you might or might not want auto-generation?
• The provided payload cannot be decrypted because it was not protected with this protection provider. For more information go to http://aka.ms/dataprotectionwarning
  • Produced for two distinct conditions: a) too short to contain metadata; b) couldn't read version from metadata
  • Link to a general doc about protection providers?
• The key {0:B} was not found in the key ring. For more information go to http://aka.ms/dataprotectionwarning
  • Maybe describe how to enumerate keys in the key ring?
• The key {0:B} already exists in the keyring. For more information go to http://aka.ms/dataprotectionwarning
  • We only detect duplicate keys on enumeration? Feels like we could just use the first one and log a warning, assuming it's even possible
• The payload is invalid. For more information go to http://aka.ms/dataprotectionwarning
  • Could probably use an explanation of how this could arise
• The payload was invalid. For more information go to http://aka.ms/dataprotectionwarning
  • This is used in two scenarios: if the message isn't long enough to contain the required metadata and if MAC validation fails. I assume we are specifically not flagging MAC validation failures as such for security reasons, so it's not obvious what troubleshooting steps we could provide

[amcasey]

There are some anomalies. When we throw the former, we log the latter:

+ The key ring does not contain a valid default protection key. The data protection system cannot create a new key because auto-generation of keys is disabled. For more information go to http://aka.ms/dataprotectionwarning
- The key ring does not contain a valid default key, and the key manager is configured with auto-generation of keys disabled.

Similarly

+ Storing keys in a directory '{path}' that may not be persisted outside of the container. Protected data will be unavailable when container is destroyed. For more information go to http://aka.ms/dataprotectionwarning
- Storing keys in a directory '{path}' that may not be persisted outside of the container. Protected data will be unavailable when container is destroyed.

In the second case, only the log message is used - the resource string is not.

The other resources strings don't obviously have log counterparts.

[amcasey]

An error occurred during a cryptographic operation. For more information go to http://aka.ms/dataprotectionwarning

Turns out there are three copies of this resources string: Abstractions, DataProtection, and Extensions. The one in Abstractions is missing the URL.

[amcasey]

I found a couple more linking messages in Extensions:

• The payload expired at {0}. For more information go to http://aka.ms/dataprotectionwarning
  • Seems self-explanatory
• The payload is invalid. For more information go to http://aka.ms/dataprotectionwarning
  • Could probably use an explanation of how this could arise

[amcasey]

In 8.0, the error messages will show https://aka.ms/aspnet/dataprotectionwarning, which points to https://learn.microsoft.com/aspnet/core/security/data-protection/configuration. Older releases will still show https://aka.ms/dataprotectionwarning, which now links to https://learn.microsoft.com/en-us/dotnet/standard/security/how-to-use-data-protection.

[amcasey]

Filed #50560 for the remaining work (to be completed once I know more about Data Protection and can sensibly explain the error messages that need explanations).