AGENTS.md

1# compat/openssl — Guide for AI Agents
2 
3Instructions for AI agents adapting the OpenSSL compatibility layer when new BoringSSL
4symbols are needed (typically after bumping gRPC, BoringSSL, or other deps).
5 
6See `README.md` in this directory for the full architectural background.
7 
8## Architecture in brief
9 
10Envoy is built against the BoringSSL API. The compat layer lets it run on OpenSSL instead.
11 
121. **Prefixer** (`prefixer/prefixer.cpp`) copies OpenSSL headers, adding an `ossl_` prefix
13   to every identifier. Output lands in `include/ossl/openssl/*.h`. It also generates
14   `source/ossl.c` (forwarding functions via dlsym) and `include/ossl.h` (the `ossl` struct
15   with function pointers for every real OpenSSL function).
16 
172. **Patched BoringSSL headers** (`patch/include/openssl/*.h.sh`) start by commenting out the
18   entire BoringSSL header, then selectively uncomment the symbols the compat layer exposes.
19   The `uncomment.sh` tool handles this. The output is `include/openssl/*.h`.
20 
213. **Mapping functions** (`source/*.c` or `source/*.cc`) implement each exposed BoringSSL
22   function by calling the `ossl_`-prefixed OpenSSL equivalent.
23 
24## Key files to modify
25 
26| File | Purpose |
27|------|---------|
28| `patch/include/openssl/<header>.h.sh` | Controls which symbols from BoringSSL's `<header>.h` are exposed |
29| `BUILD` | The `mapping_func_filegroup` list — every exposed function must be listed here |
30| `source/<function>.c` or `.cc` | Handwritten mapping when auto-generation won't work |
31 
32## How to add a missing function
33 
34### Step 1: Uncomment the declaration
35 
36Add `--uncomment-func-decl <function_name>` to the appropriate `.h.sh` patch script.
37 
38Example in `ssl.h.sh`:
39```bash
40  --uncomment-func-decl SSL_get_negotiated_group \
41```
42 
43### Step 2: Add to the BUILD file
44 
45Add the function name to the `mapping_func_filegroup` list (alphabetically sorted within
46its section).
47 
48### Step 3: Decide if a handwritten source file is needed
49 
50The build system (`bazel/rules.bzl`) auto-generates a forwarding function if no handwritten
51`source/<function>.c` or `.cc` exists. The generated code handles both cases — OpenSSL
52macros and real functions — using an `#ifdef`:
53 
54```c
55// Auto-generated pattern:
56ReturnType FunctionName(args) {
57#ifdef ossl_FunctionName
58  return ossl_FunctionName(args);        // macro path (expands inline)
59#else
60  return ossl.ossl_FunctionName(args);   // function pointer path (via dlsym)
61#endif
62}
63```
64 
65**You need a handwritten source when:**
66- The BoringSSL and OpenSSL signatures differ (different arg types, arg count)
67- The semantics differ (e.g., `SSL_CTX_set1_curves_list` has an OpenSSL 3.5 bug workaround)
68- The function has no OpenSSL equivalent at all (must be implemented from scratch)
69 
70**You can rely on auto-generation when:**
71- The function exists in OpenSSL with the same signature (as a real function or macro)
72- No semantic differences need patching
73 
74## How to add a missing constant or macro
75 
76### Constant exists in both BoringSSL and OpenSSL
77 
78Add `--uncomment-macro-redef '<pattern>'` to the `.h.sh` patch script. This generates:
79 
80```c
81#ifdef ossl_CONSTANT_NAME
82#define CONSTANT_NAME ossl_CONSTANT_NAME
83#endif
84```
85 
86The constant gets OpenSSL's value. Use regex patterns to cover families:
87```bash
88  --uncomment-macro-redef 'SSL_R_[[:alnum:]_]*' \
89  --uncomment-macro-redef 'OPENSSL_INIT_[[:alnum:]_]*' \
90```
91 
92### Constant exists only in BoringSSL (no OpenSSL equivalent)
93 
94The `--uncomment-macro-redef` approach won't work because there's no `ossl_` version — the
95`#ifdef` guard will be false and the constant stays undefined.
96 
97Instead, append a standalone `#ifndef`/`#define` block at the end of the `.h.sh` script:
98 
99```bash
100cat &gt;&gt; &quot;$1&quot; &lt;&lt;'EOF'
101 
102#ifndef SSL_R_SOME_BORINGSSL_ONLY_CONSTANT
103#define SSL_R_SOME_BORINGSSL_ONLY_CONSTANT <value>
104#endif
105EOF
106```
107 
108**Choosing values:** BoringSSL and OpenSSL often use the same numeric range for different
109constants. For example, BoringSSL's `SSL_R_NO_CIPHERS_PASSED = 176` collides with OpenSSL's
110`SSL_R_NO_CERTIFICATES_RETURNED = 176`. If both appear in the same switch statement,
111you get a duplicate-case error. To avoid this, use values in a range that neither library
112uses (e.g., 10000+ for `SSL_R_*` constants). The exact values don't matter at runtime
113since OpenSSL will never produce these BoringSSL-specific error codes.
114 
115### Constant with duplicate-case-value problem
116 
117If a constant must exist but its value collides with another constant's value (e.g.,
118`ERR_R_OVERFLOW` aliased to `ERR_R_INTERNAL_ERROR`), give it a unique value. Check
119OpenSSL's range for the constant family in `bazel-envoy/external/openssl/include/openssl/`
120and pick a value above the highest used one.
121 
122## uncomment.sh — common options
123 
124| Option | Effect |
125|--------|--------|
126| `--uncomment-func-decl <name>` | Uncomment a function declaration |
127| `--uncomment-macro '<pattern>'` | Uncomment a `#define` (keeps BoringSSL's value) |
128| `--uncomment-macro-redef '<pattern>'` | Redefine macro to use OpenSSL's value via `ossl_` prefix |
129| `--uncomment-enum <name>` | Uncomment an enum definition |
130| `--uncomment-struct <name>` | Uncomment a struct definition |
131| `--uncomment-typedef <name>` | Uncomment a typedef |
132| `--uncomment-typedef-redef <name>` | Redefine a typedef to use OpenSSL's type |
133| `--uncomment-regex '<pattern>'` | Uncomment lines matching a regex |
134| `--uncomment-regex-range '<start>' '<end>'` | Uncomment a multi-line block |
135| `--sed '<expression>'` | Run an arbitrary sed expression on the file |
136 
137## Inspecting generated output
138 
139To see what the compat layer actually produces after patching/prefixing, look in the bazel
140output directory. The exact path depends on the build configuration:
141 
142```
143bazel-out/k8-fastbuild/bin/compat/openssl/include/openssl/<header>.h   # patched BoringSSL header
144bazel-out/k8-fastbuild/bin/compat/openssl/include/ossl/openssl/<header>.h  # prefixed OpenSSL header
145bazel-out/k8-fastbuild/bin/compat/openssl/include/ossl.h              # ossl struct definition
146bazel-out/k8-fastbuild/bin/compat/openssl/source/<function>.c         # auto-generated mapping
147```
148 
149Check the prefixed OpenSSL headers to determine:
150- Whether an `ossl_<symbol>` exists (i.e., whether `--uncomment-macro-redef` will work)
151- Whether a symbol is a macro or a real function in OpenSSL
152- What numeric value OpenSSL assigns to a constant
153 
154Check the `ossl.h` struct to see which OpenSSL functions are available as function pointers
155(only real functions, not macros).
156 
157## Typical workflow for fixing build errors after a dep bump
158 
1591. **Read the errors.** Group them by type: undeclared functions, undeclared constants,
160   duplicate case values.
161 
1622. **For each undeclared function:**
163   - Check if it exists in BoringSSL (`bazel-envoy/external/boringssl/include/openssl/`)
164   - Check if it exists in OpenSSL (`bazel-envoy/external/openssl/include/openssl/`)
165   - Add `--uncomment-func-decl` to the patch script + entry in BUILD
166   - If OpenSSL's semantics differ, write a handwritten source file
167 
1683. **For each undeclared constant:**
169   - Check if it exists in both BoringSSL and OpenSSL
170   - If yes: use `--uncomment-macro-redef` in the patch script
171   - If BoringSSL-only: append a `#ifndef`/`#define` with a collision-free value
172 
1734. **For duplicate case values:**
174   - Identify which constants share the same numeric value
175   - Give the BoringSSL-only constant a unique value outside both libraries' ranges
176 
1775. **Build and iterate** — new symbols may trigger further missing-symbol errors as
178   more code becomes reachable.
179