Just a few questions and enhancements for your REST API

[ajdergute]

This is a very clean API. Good job! Just a few thoughts from my side:

1. In general it could be an idea to pass information for encodings via header, not query parameter. This could be done via Content-Type- and Accept-Headers. Maybe a custom type should be added.

2. requestAttributes:
   

   TameMyCerts.REST/TameMyCerts.REST.xml

   Line 42 in 7c13c42

   <param name="requestAttributes">

   
   As a user I've no clue which optional attributes are allowed.

3. TimeSpan:
   

   TameMyCerts.REST/TameMyCerts.REST.xml

   Line 837 in 7c13c42

   <member name="P:TameMyCerts.NetCore.Common.Models.CertificateTemplate.ValidityPeriod">

   
   In Swagger-UI this is rendered as TimeSpan. This is implementation specific. At level of API this should be a date formatted as ISO 8601 or similar.

4. What's the difference between a certificate authority certificate and it's exchange certificate?

[Sleepw4lker]

Thanks for your feedback @ajdergute which I highly appreciate.

Regarding 1.):
I'll look into it.

Regarding 2.):
Request Attributes are ADCS-specific, so the API just passed them through. Request Attributes are name:value pairs that can be used to influence the certificate issuance. For example, the desired certificate template is passed as "CertificateTemplate:Template-Name-here" (in fact, the ?templateName argument is just for convenience, it is passed as request attribute to the CA in the backend).

Other examples include modifying the Subject DN, or specifying an expiration time shorter than what is specified in the certificate template (if allowed by the CA configuration). But as this is an AD CS feature, I didn't document that separately.

Regarding 3.):
True, I'll look into it.

Regarding 4.):
The CA exchange certificate is a short-lived certificate that is used to transfer confidential information to the CA (client uses the CA exchange certificate public key to encrypt, then the CA can decrypt using the associated private key). This is mainly used for archival of the user's private key (mainly used in S/MIME or data encryption scenarios). Again, this is AD CS specific, thus I didn't document that separately. Maybe we could refer to the original Microsoft documentation.