From 4f131cf1770bb7ebcfbf56b72b2164f23007628b Mon Sep 17 00:00:00 2001
From: Jean-Christophe Amiel <jeanchristophe.amiel@orange.com>
Date: Wed, 5 Jun 2024 13:50:01 +0200
Subject: [PATCH] Add comment on SSL certificate's subject and issuer parsing.

---
 packages/hurl/src/http/certificate.rs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/hurl/src/http/certificate.rs b/packages/hurl/src/http/certificate.rs
index 494067586c1..7d1745a3892 100644
--- a/packages/hurl/src/http/certificate.rs
+++ b/packages/hurl/src/http/certificate.rs
@@ -54,6 +54,23 @@ impl TryFrom<CertInfo> for Certificate {
     }
 }
 
+/// Parses certificate's subject attribute.
+///
+/// TODO: we're exposing the subject and issuer directly from libcurl. In the certificate, these
+/// properties are list of pair of key-value.
+/// Through libcurl, these lists are serialized to a string:
+///
+/// Example:
+/// vec![("C","US"),("O","Google Trust Services LLC"),("CN","GTS Root R1"))] =>
+/// "C = US, O = Google Trust Services LLC, CN = GTS Root R1"
+///
+/// We should normalize the serialization (use 'A = B' or 'A=B') to always have the same issuer/
+/// subject given a certain certificate. Actually the value can differ on different platforms, for
+/// a given certificate.
+///
+/// See:
+/// - <integration/hurl/ssl/cacert_to_json.out.pattern>
+/// - https://curl.se/mail/lib-2024-06/0013.html
 fn parse_subject(attributes: &HashMap<String, String>) -> Result<String, String> {
     match attributes.get("subject") {
         None => Err(format!("missing Subject attribute in {attributes:?}")),
@@ -61,6 +78,7 @@ fn parse_subject(attributes: &HashMap<String, String>) -> Result<String, String>
     }
 }
 
+/// Parses certificate's issuer attribute.
 fn parse_issuer(attributes: &HashMap<String, String>) -> Result<String, String> {
     match attributes.get("issuer") {
         None => Err(format!("missing Issuer attribute in {attributes:?}")),