From 09b9ff1f4b92abcf1ad599fbd510ee6657dfc500 Mon Sep 17 00:00:00 2001 From: Alex Rousskov Date: Fri, 8 May 2026 09:26:25 -0400 Subject: [PATCH 1/4] Fix EOM description in certificate validator helpers docs * SslServerCertValidator and the corresponding AddonHelpers section incorrectly claimed that "Input received from Squid" is "delimited by a 0x01 byte instead of the standard \n byte". The opposite is true. * SslServerCertValidator and the corresponding AddonHelpers section incorrectly implied that "Result line sent back to Squid" is delimited by new lines typical to other helpers. In reality, these helper responses are delimited by ASCII SOH (0x01) bytes. * SslServerCertValidator syntax descriptions poorly duplicated the corresponding AddonHelpers sections. SslServerCertValidator "Input line received from Squid" section contained a malformed table. * AddonHelpers section for "SSL certificate generation" had malformed "warning" markup and malformed title row in the key=value table. Duplicated SslServerCertValidator sections are now removed. Message delimiter (a.k.a. EOM character) documentation in the corresponding AddonHelpers sections are now fixed, along with tje identified markup problems. Also improved related message syntax descriptions to improve phrasing and to be more explicit about odd spacing format that, for example, has a dangling SP character after zero body size. TODO: Fix similar problems in certificate _generator_ sections. --- docs/Features/AddonHelpers.md | 74 +++++++++++------------ docs/Features/SslServerCertValidator.md | 79 +------------------------ 2 files changed, 38 insertions(+), 115 deletions(-) diff --git a/docs/Features/AddonHelpers.md b/docs/Features/AddonHelpers.md index c5fc5c6b..a0539d60 100644 --- a/docs/Features/AddonHelpers.md +++ b/docs/Features/AddonHelpers.md @@ -1119,32 +1119,27 @@ Result line sent back to Squid: This interface is similar to the SSL certificate generation interface. -Input *line* received from Squid: +Request messages sent by Squid have the following syntax: - request size [kv-pairs] + action SP size SP body LF -![/\!\\](https://wiki.squid-cache.org/wiki/squidtheme/img/alert.png) -*line* refers to a logical input. **body** may contain \\n characters so -each line in this format is delimited by a 0x01 byte instead of the -standard \\n byte. +... where `SP` is an ASCII space character, and `LF` is an ASCII new line +character (\\n), and the other three fields are documented below. - - request - - - The type of action being requested. Presently the code - **cert\_validate** is the only request made. +:warning: The `body` field usually contains new line characters. Use the +`size` field to find the end of the body. - - size - - - Total size of the following request bytes taken by the - **key=pair** parameters. +- action: A string with the name of helper operation being requested. Squid + currently only sends `cert_validate` requests. - - kv-pairs - - - An optional list of key=value parameters separated by new lines. - Supported parameters are: - - | | | - | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +- size: A decimal number representing the size of the `body` field in bytes. + The size of an empty `body` is zero. + +- body: A possibly empty list of the following key=value pairs separated by + ASCII new line characters (\\n). + + | key | value description | + | --------------------- | --------------------------- | | host | FQDN host name or the domain | | proto\_version | The SSL/TLS version | | cipher | The SSL/TLS cipher being used | @@ -1164,40 +1159,41 @@ Example request: error_name_0=X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error_cert_0=cert0 -Result line sent back to Squid: - result size kv-pairs +Squid expects response messages with the following syntax: - - result - - - One of the result codes: + result SP size SP body SOH + +... where `SP` is an ASCII space character, `SOH` is an ASCII Start of Heading +character (with the value of 1), and the other three fields are documented +below. + +:warning: The `body` field usually contains new line characters. Use the +`size` field to find the end of the body. + +- result: A string matching one of the following codes: - | | | + | code| code meaning | | --- | ------------------------------------------ | | OK | Success. Certificate validated. | | ERR | Success. Certificate not validated. | | BH | Failure. The helper encountered a problem. | +- size: A decimal number representing the size of the `body` field in bytes. + The size of an empty `body` is zero. - - size - - - Total size of the following response bytes taken by the - **key=pair** parameters. +- body: A possibly empty list of the following key=value pairs separated by + ASCII new line characters (\\n). - - kv-pairs - - - A list of key=value parameters separated by new lines. The - supported parameters are: - - | | | - | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- | + | key | value description | + | ----------------------- | --------------------------- | | cert\_***ID*** | A certificate send from helper to squid. The **ID** is an index number for this certificate | | error\_name\_***ID*** | The openSSL error name for the error **ID** | | error\_reason\_***ID*** | A reason for the error **ID** | | error\_cert\_***ID*** | The broken certificate. It can be one of the certificates sent by helper to squid or one of those sent by squid to helper | -Example response message: +Example response message (with the terminating SOH character not shown): ERR 1444 cert_10=-----BEGIN CERTIFICATE----- MIIDojCCAoqgAwIBAgIQE4Y1TR0/BvLB+WUF1ZAcYjANBgkqhkiG9w0BAQUFADBr diff --git a/docs/Features/SslServerCertValidator.md b/docs/Features/SslServerCertValidator.md index ae4c5e98..45077b78 100644 --- a/docs/Features/SslServerCertValidator.md +++ b/docs/Features/SslServerCertValidator.md @@ -56,82 +56,9 @@ triggering the existing SSL error processing code. Helper responses will be cached to reduce validation performance burden (indexed by validation query parameters). -## Helper communication protocol - -This interface is similar to the SSL certificate generation interface. - -Input *line* received from Squid: - - request size [kv-pairs] - -> :warning: - *line* refers to a logical input. **body** may contain \\n characters so - each line in this format is delimited by a 0x01 byte instead of the - standard \\n byte. - -- request -: The type of action being requested. Presently the code - **cert_validate** is the only request made. -- size -: Total size of the following request bytes taken by the - **key=pair** parameters. -- kv-pairs -: An optional list of key=value parameters separated by new lines. - Supported parameters are: - | --- | --- | - | host | FQDN host name or the domain | - | proto_version | The SSL/TLS version | - | cipher | The SSL/TLS cipher being used | - | cert_***ID*** | Server certificate. The ID is an index number for this certificate. This parameter exist as many as the server certificates are | - | error_name_***ID*** | The openSSL certificate validation error. The ID is an index number for this error | - | error_cert_***ID*** | The ID of the certificate which caused error_name_ID | - -Example request: - - 0 cert_validate 1519 host=dmz.example-domain.com - cert_0=-----BEGIN CERTIFICATE----- - MIID+DCCA2GgAwIBAgIJAIDcHRUxB2O4MA0GCSqGSIb3DQEBBAUAMIGvMQswCQYD - ... - YpVJGt5CJuNfCcB/ - -----END CERTIFICATE----- - error_name_0=X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT - error_cert_0=cert0 - -Result line sent back to Squid: - - result size kv-pairs - -- result -: One of the result codes: - - | --- | ------------------------------------------ | - | OK | Success. Certificate validated. | - | ERR | Success. Certificate not validated. | - | BH | Failure. The helper encountered a problem. | - -- size -: Total size of the following response bytes taken by the - **key=pair** parameters. -- kv-pairs -: A list of key=value parameters separated by new lines. The - supported parameters are: - - | --- | --- | - | cert_***ID*** | A certificate send from helper to squid. The **ID** is an index number for this certificate | - | error_name_***ID*** | The openSSL error name for the error **ID** | - | error_reason_***ID*** | A reason for the error **ID** | - | error_cert_***ID*** | The broken certificate. It can be one of the certificates sent by helper to squid or one of those sent by squid to helper | - -Example response message: - - ERR 1444 cert_10=-----BEGIN CERTIFICATE----- - MIIDojCCAoqgAwIBAgIQE4Y1TR0/BvLB+WUF1ZAcYjANBgkqhkiG9w0BAQUFADBr - ... - 398znM/jra6O1I7mT1GvFpLgXPYHDw== - -----END CERTIFICATE----- - error_name_0=X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT - error_reason_0=Checked by Cert Validator - error_cert_0=cert_10 +Helper communication protocol will be similar to the one used by the x509 +certificate generator helper, as documented +[elsewhere](Features/AddonHelpers). ## Design decision points From 064b8e07f504370e612a2b80e8d493a873181ed3 Mon Sep 17 00:00:00 2001 From: Alex Rousskov Date: Fri, 8 May 2026 10:40:37 -0400 Subject: [PATCH 2/4] Fixed one more problem: broken concurrency support docs * The `request-ID` field was not documented; `cert_validate` request example used an invalid request-ID value of zero, while the response example did not use a `request-ID` field at all. We now document `request-ID` fields in requests and responses. The two examples use matching request-ID values. N.B. Syntax descriptions for other helpers use misleading "channel-ID" phrasing that implies that Squid may send multiple requests (or can handle multiple responses) sent over the same communication "channel". In reality, concurrency is implemented using unique request IDs; there is no reusable "channel" in this context. Most request IDs exceed `concurrency=N` parameter. These differences can have a significant impact on helper implementations. I believe there were questions about this on Squid forums. TODO: Use `request-ID` terminology in all relevant descriptions. --- docs/Features/AddonHelpers.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/Features/AddonHelpers.md b/docs/Features/AddonHelpers.md index a0539d60..771f0876 100644 --- a/docs/Features/AddonHelpers.md +++ b/docs/Features/AddonHelpers.md @@ -1121,14 +1121,21 @@ This interface is similar to the SSL certificate generation interface. Request messages sent by Squid have the following syntax: - action SP size SP body LF + [request-ID SP] action SP size SP body LF ... where `SP` is an ASCII space character, and `LF` is an ASCII new line -character (\\n), and the other three fields are documented below. +character (\\n), and the other fields are documented below. :warning: The `body` field usually contains new line characters. Use the `size` field to find the end of the body. +- request-ID: An unsigned positive 64-bit decimal number uniquely identifying + this request among all requests submitted to this helper process (i.e. on + this helper stdin connection). Squid sends this field when (and only when) + the `concurrency=N` helper configuration option is used with `N` values + grater than 1. When this field is present, the corresponding helper response + must start with a matching `response-ID` field. + - action: A string with the name of helper operation being requested. Squid currently only sends `cert_validate` requests. @@ -1150,7 +1157,7 @@ character (\\n), and the other three fields are documented below. Example request: - 0 cert_validate 1519 host=dmz.example-domain.com + 17179869184 cert_validate 1519 host=dmz.example-domain.com cert_0=-----BEGIN CERTIFICATE----- MIID+DCCA2GgAwIBAgIJAIDcHRUxB2O4MA0GCSqGSIb3DQEBBAUAMIGvMQswCQYD ... @@ -1162,15 +1169,19 @@ Example request: Squid expects response messages with the following syntax: - result SP size SP body SOH + [request-ID SP] result SP size SP body SOH ... where `SP` is an ASCII space character, `SOH` is an ASCII Start of Heading -character (with the value of 1), and the other three fields are documented -below. +character (with the value of 1), and the other fields are documented below. :warning: The `body` field usually contains new line characters. Use the `size` field to find the end of the body. +- request-ID: An unsigned positive 64-bit decimal number equal to the + `request-ID` field of the corresponding helper request. This field must be + sent when (and only when) the `concurrency=N` helper configuration option is + used with `N` values grater than 1. + - result: A string matching one of the following codes: | code| code meaning | @@ -1195,7 +1206,7 @@ below. Example response message (with the terminating SOH character not shown): - ERR 1444 cert_10=-----BEGIN CERTIFICATE----- + 17179869184 ERR 1444 cert_10=-----BEGIN CERTIFICATE----- MIIDojCCAoqgAwIBAgIQE4Y1TR0/BvLB+WUF1ZAcYjANBgkqhkiG9w0BAQUFADBr ... 398znM/jra6O1I7mT1GvFpLgXPYHDw== From 92bef84aea8663f27586cd92105c7a4299cc06ad Mon Sep 17 00:00:00 2001 From: Alex Rousskov Date: Fri, 8 May 2026 10:50:18 -0400 Subject: [PATCH 3/4] fixup: Do show the terminating SOH character in the example --- docs/Features/AddonHelpers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Features/AddonHelpers.md b/docs/Features/AddonHelpers.md index 771f0876..9e1173ee 100644 --- a/docs/Features/AddonHelpers.md +++ b/docs/Features/AddonHelpers.md @@ -1204,7 +1204,7 @@ character (with the value of 1), and the other fields are documented below. | error\_cert\_***ID*** | The broken certificate. It can be one of the certificates sent by helper to squid or one of those sent by squid to helper | -Example response message (with the terminating SOH character not shown): +Example response message (with the terminating SOH character shown as `^A`): 17179869184 ERR 1444 cert_10=-----BEGIN CERTIFICATE----- MIIDojCCAoqgAwIBAgIQE4Y1TR0/BvLB+WUF1ZAcYjANBgkqhkiG9w0BAQUFADBr @@ -1213,7 +1213,7 @@ Example response message (with the terminating SOH character not shown): -----END CERTIFICATE----- error_name_0=X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error_reason_0=Checked by Cert Validator - error_cert_0=cert_10 + error_cert_0=cert_10^A ### Cache file eraser From 17d0cce607f268bb774596d8a3d1da9e4a8b1cda Mon Sep 17 00:00:00 2001 From: Alex Rousskov Date: Fri, 8 May 2026 11:10:38 -0400 Subject: [PATCH 4/4] fixup: Minor polishing of changed text --- docs/Features/AddonHelpers.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/Features/AddonHelpers.md b/docs/Features/AddonHelpers.md index 9e1173ee..7f8c34ae 100644 --- a/docs/Features/AddonHelpers.md +++ b/docs/Features/AddonHelpers.md @@ -1123,7 +1123,7 @@ Request messages sent by Squid have the following syntax: [request-ID SP] action SP size SP body LF -... where `SP` is an ASCII space character, and `LF` is an ASCII new line +... where `SP` is an ASCII space character, `LF` is an ASCII new line character (\\n), and the other fields are documented below. :warning: The `body` field usually contains new line characters. Use the @@ -1134,10 +1134,10 @@ character (\\n), and the other fields are documented below. this helper stdin connection). Squid sends this field when (and only when) the `concurrency=N` helper configuration option is used with `N` values grater than 1. When this field is present, the corresponding helper response - must start with a matching `response-ID` field. + must start with a matching `request-ID` field. -- action: A string with the name of helper operation being requested. Squid - currently only sends `cert_validate` requests. +- action: A string with the name of the helper operation being requested. + Squid currently only sends `cert_validate` requests. - size: A decimal number representing the size of the `body` field in bytes. The size of an empty `body` is zero. @@ -1171,14 +1171,16 @@ Squid expects response messages with the following syntax: [request-ID SP] result SP size SP body SOH -... where `SP` is an ASCII space character, `SOH` is an ASCII Start of Heading -character (with the value of 1), and the other fields are documented below. +... where `SP` is an ASCII space character, `SOH` is an ASCII "Start of +Heading" character (with the value of 1), and the other fields are documented +below. -:warning: The `body` field usually contains new line characters. Use the -`size` field to find the end of the body. +:warning: If the response `body` field is empty or contains a single key=value +pair that has no embedded new lines, then the entire response message should +have no new line characters. - request-ID: An unsigned positive 64-bit decimal number equal to the - `request-ID` field of the corresponding helper request. This field must be + `request-ID` field of the corresponding helper request. These fields must be sent when (and only when) the `concurrency=N` helper configuration option is used with `N` values grater than 1.