Coverage Report

Created: 2024-01-20 12:34

/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