Clang 18 compilation errors with strict warning flags (-Werror enabled)

[HyukjinKwon]

Problem:

s2n-tls v1.5.23 (and latest main branch) fails to compile with Clang 18 when strict warning flags are enabled (-Werror -Wdocumentation -Wshorten-64-to-32).

api/s2n.h:323:11: error: parameter 'void*' not found in the function declaration [-Werror,-Wdocumentation]
api/s2n.h:324:11: error: parameter 'uint64_t*' not found in the function declaration [-Werror,-Wdocumentation]
api/s2n.h:795:5: error: declaration is marked with '@deprecated' command but does not have a deprecation attribute [-Werror,-Wdocumentation-deprecated-sync]
api/s2n.h:1195:5: error: declaration is marked with '@deprecated' command but does not have a deprecation attribute [-Werror,-Wdocumentation-deprecated-sync]
api/s2n.h:2441:11: error: parameter 'cert_chain_out' not found in the function declaration [-Werror,-Wdocumentation]
api/s2n.h:3163:11: error: parameter 'conn' not found in the function declaration [-Werror,-Wdocumentation]
api/s2n.h:3218:11: error: parameter 'cert_match' not found in the function declaration [-Werror,-Wdocumentation]
api/s2n.h:3299:5: error: declaration is marked with '@deprecated' command but does not have a deprecation attribute [-Werror,-Wdocumentation-deprecated-sync]
api/s2n.h:3309:5: error: declaration is marked with '@deprecated' command but does not have a deprecation attribute [-Werror,-Wdocumentation-deprecated-sync]
crypto/s2n_certificate.c:143:62: error: implicit conversion loses integer precision: 'unsigned long' to 'uint32_t' [-Werror,-Wshorten-64-to-32]
crypto/s2n_certificate.c:221:31: error: implicit conversion loses integer precision: 'size_t' to 'int' [-Werror,-Wshorten-64-to-32]
crypto/s2n_certificate.c:238:37: error: implicit conversion loses integer precision: 'const size_t' to 'uint32_t' [-Werror,-Wshorten-64-to-32]
crypto/s2n_certificate.c:243:30: error: implicit conversion loses integer precision: 'const size_t' to 'uint32_t' [-Werror,-Wshorten-64-to-32]
crypto/s2n_certificate.c:796:60: error: implicit conversion loses integer precision: 'size_t' to 'int' [-Werror,-Wshorten-64-to-32]

Need By Date:

No strict deadline.

Solution:

Fix documentation parameter names in api/s2n.h, add deprecation attributes in api/s2n.h, add explicit casts in crypto/s2n_certificate.c, etc.

• Does this change what S2N sends over the wire? No. These are documentation and type safety fixes with no functional changes.

• Does this change any public APIs? No. The API declarations remain the same; only documentation comments and internal type conversions are affected.

• Which versions of TLS will this impact? None. These are code quality improvements with no protocol-level changes.

Requirements / Acceptance Criteria:

• Code compiles without errors with Clang 18 and flags: -Werror -Wdocumentation -Wshorten-64-to-32

• All existing tests pass

• Documentation parameters match function signatures

• Deprecated functions have proper attributes

• No implicit integer conversions that could lose precision

• RFC links: Not applicable (code quality fix)

• Related Issues:

  • Clang 18 documentation: https://clang.llvm.org/docs/DiagnosticsReference.html#wdocumentation

• Will the Usage Guide or other documentation need to be updated? No, only inline documentation comments.

• Testing:

  • Verify compilation with Clang 18 + strict flags passes

  • Will this change trigger SAW changes? No, these are documentation and type cast changes only.

  • Should this change be fuzz tested? No, no logic changes to test.

[jmayclin]

Future note: when we fix this we should ensure that we add CI coverage with these flags enabled to ensure that we don't regress, but note that these options are only available on Clang, so we'll have to handle that in our CMakeLists.txt

[itsdevandy]

Hi @jmayclin , may I work on this? I've reproduced the issue using Clang 18 and the specified strict flags.

[maddeleine]

Feel free to take a whack at this @itsdevandy!