TLSRPT documentation can benefit from more examples

[wietse-postfix]

Some time ago, Boris wrote in email:

I have a first version of the TLSRPT library that should fullfill all requirements needed to handle the different cases of RFC8460.

This message also included a few examples, which I found to be very useful to supplement the API definition document.

For reference, I have attached a copy of that file because I could not find it on github: example.txt

One suggestion for improvement is to make clear when tlsrpt_add_mx_host_pattern() is supposed to be called:

• The STS example has tlsrpt_add_mx_host_pattern() calls.

• The TLSA example has NO tlsrpt_add_mx_host_pattern() calls.

https://datatracker.ietf.org/doc/html/rfc8460#section-4.4 says that MX patterns are relevant for STS, and doesn't mention them in the context of TLSA. I suppose we should not specify MX patterms with TLSA, because they are not expected there.

I know that examples are not a definition, but it is very hard to write a complete definition, and for readers, it is hard to learn to use an API without examples, like learning to speak a language from a dictionary.

I suggest a few more examples:

• A domain with DANE and STS policies

• A delivery request with a combination of failure and success.

[BLohner]

https://datatracker.ietf.org/doc/html/rfc8460#section-4.4 says that MX patterns are relevant for STS, and doesn't mention them in the context of TLSA. I suppose we should not specify MX patterms with TLSA, because they are not expected there.

Exactly.