/src/openssl/include/openssl/trace.h
Line | Count | Source (jump to first uncovered line) |
1 | | /* |
2 | | * Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. |
3 | | * |
4 | | * Licensed under the Apache License 2.0 (the "License"). You may not use |
5 | | * this file except in compliance with the License. You can obtain a copy |
6 | | * in the file LICENSE in the source distribution or at |
7 | | * https://www.openssl.org/source/license.html |
8 | | */ |
9 | | |
10 | | #ifndef OPENSSL_TRACE_H |
11 | | # define OPENSSL_TRACE_H |
12 | | |
13 | | # include <stdarg.h> |
14 | | |
15 | | # include <openssl/bio.h> |
16 | | |
17 | | # ifdef __cplusplus |
18 | | extern "C" { |
19 | | # endif |
20 | | |
21 | | /* |
22 | | * TRACE CATEGORIES |
23 | | */ |
24 | | |
25 | | /* |
26 | | * The trace messages of the OpenSSL libraries are organized into different |
27 | | * categories. For every trace category, the application can register a separate |
28 | | * tracer callback. When a callback is registered, a so called trace channel is |
29 | | * created for this category. This channel consists essentially of an internal |
30 | | * BIO which sends all trace output it receives to the registered application |
31 | | * callback. |
32 | | * |
33 | | * The ALL category can be used as a fallback category to register a single |
34 | | * channel which receives the output from all categories. However, if the |
35 | | * application intends to print the trace channel name in the line prefix, |
36 | | * it is better to register channels for all categories separately. |
37 | | * (This is how the openssl application does it.) |
38 | | */ |
39 | | # define OSSL_TRACE_CATEGORY_ALL 0 /* The fallback */ |
40 | | # define OSSL_TRACE_CATEGORY_TRACE 1 |
41 | | # define OSSL_TRACE_CATEGORY_INIT 2 |
42 | | # define OSSL_TRACE_CATEGORY_TLS 3 |
43 | | # define OSSL_TRACE_CATEGORY_TLS_CIPHER 4 |
44 | | # define OSSL_TRACE_CATEGORY_CONF 5 |
45 | | # define OSSL_TRACE_CATEGORY_ENGINE_TABLE 6 |
46 | | # define OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT 7 |
47 | | # define OSSL_TRACE_CATEGORY_PKCS5V2 8 |
48 | | # define OSSL_TRACE_CATEGORY_PKCS12_KEYGEN 9 |
49 | | # define OSSL_TRACE_CATEGORY_PKCS12_DECRYPT 10 |
50 | | # define OSSL_TRACE_CATEGORY_X509V3_POLICY 11 |
51 | | # define OSSL_TRACE_CATEGORY_BN_CTX 12 |
52 | 1.36k | # define OSSL_TRACE_CATEGORY_CMP 13 |
53 | | # define OSSL_TRACE_CATEGORY_STORE 14 |
54 | | # define OSSL_TRACE_CATEGORY_NUM 15 |
55 | | |
56 | | /* Returns the trace category number for the given |name| */ |
57 | | int OSSL_trace_get_category_num(const char *name); |
58 | | |
59 | | /* Returns the trace category name for the given |num| */ |
60 | | const char *OSSL_trace_get_category_name(int num); |
61 | | |
62 | | /* |
63 | | * TRACE CONSUMERS |
64 | | */ |
65 | | |
66 | | /* |
67 | | * Enables tracing for the given |category| by providing a BIO sink |
68 | | * as |channel|. If a null pointer is passed as |channel|, an existing |
69 | | * trace channel is removed and tracing for the category is disabled. |
70 | | * |
71 | | * Returns 1 on success and 0 on failure |
72 | | */ |
73 | | int OSSL_trace_set_channel(int category, BIO* channel); |
74 | | |
75 | | /* |
76 | | * Attach a prefix and a suffix to the given |category|, to be printed at the |
77 | | * beginning and at the end of each trace output group, i.e. when |
78 | | * OSSL_trace_begin() and OSSL_trace_end() are called. |
79 | | * If a null pointer is passed as argument, the existing prefix or suffix is |
80 | | * removed. |
81 | | * |
82 | | * They return 1 on success and 0 on failure |
83 | | */ |
84 | | int OSSL_trace_set_prefix(int category, const char *prefix); |
85 | | int OSSL_trace_set_suffix(int category, const char *suffix); |
86 | | |
87 | | /* |
88 | | * OSSL_trace_cb is the type tracing callback provided by the application. |
89 | | * It MUST return the number of bytes written, or 0 on error (in other words, |
90 | | * it can never write zero bytes). |
91 | | * |
92 | | * The |buffer| will always contain text, which may consist of several lines. |
93 | | * The |data| argument points to whatever data was provided by the application |
94 | | * when registering the tracer function. |
95 | | * |
96 | | * The |category| number is given, as well as a |cmd| number, described below. |
97 | | */ |
98 | | typedef size_t (*OSSL_trace_cb)(const char *buffer, size_t count, |
99 | | int category, int cmd, void *data); |
100 | | /* |
101 | | * Possible |cmd| numbers. |
102 | | */ |
103 | | # define OSSL_TRACE_CTRL_BEGIN 0 |
104 | | # define OSSL_TRACE_CTRL_WRITE 1 |
105 | | # define OSSL_TRACE_CTRL_END 2 |
106 | | |
107 | | /* |
108 | | * Enables tracing for the given |category| by creating an internal |
109 | | * trace channel which sends the output to the given |callback|. |
110 | | * If a null pointer is passed as callback, an existing trace channel |
111 | | * is removed and tracing for the category is disabled. |
112 | | * |
113 | | * NOTE: OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually |
114 | | * exclusive. |
115 | | * |
116 | | * Returns 1 on success and 0 on failure |
117 | | */ |
118 | | int OSSL_trace_set_callback(int category, OSSL_trace_cb callback, void *data); |
119 | | |
120 | | /* |
121 | | * TRACE PRODUCERS |
122 | | */ |
123 | | |
124 | | /* |
125 | | * Returns 1 if tracing for the specified category is enabled, otherwise 0 |
126 | | */ |
127 | | int OSSL_trace_enabled(int category); |
128 | | |
129 | | /* |
130 | | * Wrap a group of tracing output calls. OSSL_trace_begin() locks tracing and |
131 | | * returns the trace channel associated with the given category, or NULL if no |
132 | | * channel is associated with the category. OSSL_trace_end() unlocks tracing. |
133 | | * |
134 | | * Usage: |
135 | | * |
136 | | * BIO *out; |
137 | | * if ((out = OSSL_trace_begin(category)) != NULL) { |
138 | | * ... |
139 | | * BIO_fprintf(out, ...); |
140 | | * ... |
141 | | * OSSL_trace_end(category, out); |
142 | | * } |
143 | | * |
144 | | * See also the convenience macros OSSL_TRACE_BEGIN and OSSL_TRACE_END below. |
145 | | */ |
146 | | BIO *OSSL_trace_begin(int category); |
147 | | void OSSL_trace_end(int category, BIO *channel); |
148 | | |
149 | | /* |
150 | | * OSSL_TRACE* Convenience Macros |
151 | | */ |
152 | | |
153 | | /* |
154 | | * When the tracing feature is disabled, these macros are defined to |
155 | | * produce dead code, which a good compiler should eliminate. |
156 | | */ |
157 | | |
158 | | /* |
159 | | * OSSL_TRACE_BEGIN, OSSL_TRACE_END - Define a Trace Group |
160 | | * |
161 | | * These two macros can be used to create a block which is executed only |
162 | | * if the corresponding trace category is enabled. Inside this block, a |
163 | | * local variable named |trc_out| is defined, which points to the channel |
164 | | * associated with the given trace category. |
165 | | * |
166 | | * Usage: (using 'TLS' as an example category) |
167 | | * |
168 | | * OSSL_TRACE_BEGIN(TLS) { |
169 | | * |
170 | | * BIO_fprintf(trc_out, ... ); |
171 | | * |
172 | | * } OSSL_TRACE_END(TLS); |
173 | | * |
174 | | * |
175 | | * This expands to the following code |
176 | | * |
177 | | * do { |
178 | | * BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS); |
179 | | * if (trc_out != NULL) { |
180 | | * ... |
181 | | * BIO_fprintf(trc_out, ...); |
182 | | * } |
183 | | * OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out); |
184 | | * } while (0); |
185 | | * |
186 | | * The use of the inner '{...}' group and the trailing ';' is enforced |
187 | | * by the definition of the macros in order to make the code look as much |
188 | | * like C code as possible. |
189 | | * |
190 | | * Before returning from inside the trace block, it is necessary to |
191 | | * call OSSL_TRACE_CANCEL(category). |
192 | | */ |
193 | | |
194 | | # ifndef OPENSSL_NO_TRACE |
195 | | |
196 | | # define OSSL_TRACE_BEGIN(category) \ |
197 | | do { \ |
198 | | BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_##category); \ |
199 | | \ |
200 | | if (trc_out != NULL) |
201 | | |
202 | | # define OSSL_TRACE_END(category) \ |
203 | | OSSL_trace_end(OSSL_TRACE_CATEGORY_##category, trc_out); \ |
204 | | } while (0) |
205 | | |
206 | | # define OSSL_TRACE_CANCEL(category) \ |
207 | | OSSL_trace_end(OSSL_TRACE_CATEGORY_##category, trc_out) \ |
208 | | |
209 | | # else |
210 | | |
211 | | # define OSSL_TRACE_BEGIN(category) \ |
212 | 168M | do { \ |
213 | 168M | BIO *trc_out = NULL; \ |
214 | 168M | if (0) |
215 | | |
216 | | # define OSSL_TRACE_END(category) \ |
217 | 168M | } while(0) |
218 | | |
219 | | # define OSSL_TRACE_CANCEL(category) \ |
220 | | ((void)0) |
221 | | |
222 | | # endif |
223 | | |
224 | | /* |
225 | | * OSSL_TRACE_ENABLED() - Check whether tracing is enabled for |category| |
226 | | * |
227 | | * Usage: |
228 | | * |
229 | | * if (OSSL_TRACE_ENABLED(TLS)) { |
230 | | * ... |
231 | | * } |
232 | | */ |
233 | | # ifndef OPENSSL_NO_TRACE |
234 | | |
235 | | # define OSSL_TRACE_ENABLED(category) \ |
236 | | OSSL_trace_enabled(OSSL_TRACE_CATEGORY_##category) |
237 | | |
238 | | # else |
239 | | |
240 | | # define OSSL_TRACE_ENABLED(category) (0) |
241 | | |
242 | | # endif |
243 | | |
244 | | /* |
245 | | * OSSL_TRACE*() - OneShot Trace Macros |
246 | | * |
247 | | * These macros are intended to produce a simple printf-style trace output. |
248 | | * Unfortunately, C90 macros don't support variable arguments, so the |
249 | | * "vararg" OSSL_TRACEV() macro has a rather weird usage pattern: |
250 | | * |
251 | | * OSSL_TRACEV(category, (trc_out, "format string", ...args...)); |
252 | | * |
253 | | * Where 'channel' is the literal symbol of this name, not a variable. |
254 | | * For that reason, it is currently not intended to be used directly, |
255 | | * but only as helper macro for the other oneshot trace macros |
256 | | * OSSL_TRACE(), OSSL_TRACE1(), OSSL_TRACE2(), ... |
257 | | * |
258 | | * Usage: |
259 | | * |
260 | | * OSSL_TRACE(INIT, "Hello world!\n"); |
261 | | * OSSL_TRACE1(TLS, "The answer is %d\n", 42); |
262 | | * OSSL_TRACE2(TLS, "The ultimate question to answer %d is '%s'\n", |
263 | | * 42, "What do you get when you multiply six by nine?"); |
264 | | */ |
265 | | |
266 | | # define OSSL_TRACEV(category, args) \ |
267 | 122k | OSSL_TRACE_BEGIN(category) \ |
268 | 122k | BIO_printf args; \ |
269 | 122k | OSSL_TRACE_END(category) |
270 | | |
271 | | # define OSSL_TRACE(category, text) \ |
272 | 29.4k | OSSL_TRACEV(category, (trc_out, "%s", text)) |
273 | | |
274 | | # define OSSL_TRACE1(category, format, arg1) \ |
275 | 0 | OSSL_TRACEV(category, (trc_out, format, arg1)) |
276 | | # define OSSL_TRACE2(category, format, arg1, arg2) \ |
277 | 0 | OSSL_TRACEV(category, (trc_out, format, arg1, arg2)) |
278 | | # define OSSL_TRACE3(category, format, arg1, arg2, arg3) \ |
279 | 82.5k | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3)) |
280 | | # define OSSL_TRACE4(category, format, arg1, arg2, arg3, arg4) \ |
281 | 0 | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3, arg4)) |
282 | | # define OSSL_TRACE5(category, format, arg1, arg2, arg3, arg4, arg5) \ |
283 | | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3, arg4, arg5)) |
284 | | # define OSSL_TRACE6(category, format, arg1, arg2, arg3, arg4, arg5, arg6) \ |
285 | 10.6k | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3, arg4, arg5, arg6)) |
286 | | # define OSSL_TRACE7(category, format, arg1, arg2, arg3, arg4, arg5, arg6, arg7) \ |
287 | | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3, arg4, arg5, arg6, arg7)) |
288 | | # define OSSL_TRACE8(category, format, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) \ |
289 | | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)) |
290 | | # define OSSL_TRACE9(category, format, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) \ |
291 | | OSSL_TRACEV(category, (trc_out, format, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)) |
292 | | |
293 | | # ifdef __cplusplus |
294 | | } |
295 | | # endif |
296 | | |
297 | | #endif |