search

Sleepw4lker / TameMyCerts.REST

REST API for Microsoft Active Directory Certificate Services
Apache License 2.0
22 stars 2 forks source link

Just a few questions and enhancements for your REST API #2

Open ajdergute opened 11 months ago

ajdergute commented 11 months ago

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: https://github.com/Sleepw4lker/TameMyCerts.REST/blob/7c13c429bce37d316b0764dd300a3140d3f79478/TameMyCerts.REST.xml#L42 As a user I've no clue which optional attributes are allowed.

  3. TimeSpan: https://github.com/Sleepw4lker/TameMyCerts.REST/blob/7c13c429bce37d316b0764dd300a3140d3f79478/TameMyCerts.REST.xml#L837 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 commented 11 months ago

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.