Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_record_padding_callback.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_RECORD_PADDING_CALLBACK 3SSL"
58 .TH SSL_CTX_SET_RECORD_PADDING_CALLBACK 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_record_padding_callback,
65 SSL_set_record_padding_callback,
66 SSL_CTX_set_record_padding_callback_arg,
67 SSL_set_record_padding_callback_arg,
68 SSL_CTX_get_record_padding_callback_arg,
69 SSL_get_record_padding_callback_arg,
70 SSL_CTX_set_block_padding,
71 SSL_CTX_set_block_padding_ex,
72 SSL_set_block_padding,
73 SSL_set_block_padding_ex \- install callback to specify TLS 1.3 record padding
74 .SH SYNOPSIS
75 .IX Header "SYNOPSIS"
76 .Vb 1
77 \& #include <openssl/ssl.h>
78 \&
79 \& void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
80 \& int SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
81 \&
82 \& void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg);
83 \& void *SSL_CTX_get_record_padding_callback_arg(const SSL_CTX *ctx);
84 \&
85 \& void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg);
86 \& void *SSL_get_record_padding_callback_arg(const SSL *ssl);
87 \&
88 \& int SSL_CTX_set_block_padding(SSL_CTX *ctx, size_t block_size);
89 \& int SSL_set_block_padding(SSL *ssl, size_t block_size);
90 \& int SSL_CTX_set_block_padding_ex(SSL_CTX *ctx, size_t app_block_size, size_t hs_block_size);
91 \& int SSL_set_block_padding_ex(SSL *ssl, size_t app_block_size, size_t hs_block_size);
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 \&\fBSSL_CTX_set_record_padding_callback()\fR or \fBSSL_set_record_padding_callback()\fR
96 can be used to assign a callback function \fIcb\fR to specify the padding
97 for TLS 1.3 records. The value set in \fBctx\fR is copied to a new SSL by \fBSSL_new()\fR.
98 Kernel TLS is not possible if the record padding callback is set, and the callback
99 function cannot be set if Kernel TLS is already configured for the current SSL object.
100 .PP
101 \&\fBSSL_CTX_set_record_padding_callback_arg()\fR and \fBSSL_set_record_padding_callback_arg()\fR
102 assign a value \fBarg\fR that is passed to the callback when it is invoked. The value
103 set in \fBctx\fR is copied to a new SSL by \fBSSL_new()\fR.
104 .PP
105 \&\fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR
106 retrieve the \fBarg\fR value that is passed to the callback.
107 .PP
108 \&\fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR pads the record to a multiple
109 of the \fBblock_size\fR. A \fBblock_size\fR of 0 or 1 disables block padding. The limit of
110 \&\fBblock_size\fR is SSL3_RT_MAX_PLAIN_LENGTH.
111 .PP
112 \&\fBSSL_CTX_set_block_padding_ex()\fR and \fBSSL_set_block_padding_ex()\fR do similarly but
113 allow the caller to separately specify the padding block size to be applied to
114 handshake and application data messages.
115 .PP
116 The callback is invoked for every record before encryption.
117 The \fBtype\fR parameter is the TLS record type that is being processed; may be
118 one of SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE, or SSL3_RT_ALERT.
119 The \fBlen\fR parameter is the current plaintext length of the record before encryption.
120 The \fBarg\fR parameter is the value set via \fBSSL_CTX_set_record_padding_callback_arg()\fR
121 or \fBSSL_set_record_padding_callback_arg()\fR.
122 .PP
123 These functions cannot be used with QUIC SSL objects.
124 \&\fBSSL_set_record_padding_callback()\fR and \fBSSL_set_block_padding()\fR fail if called on
125 a QUIC SSL object.
126 .SH "RETURN VALUES"
127 .IX Header "RETURN VALUES"
128 The \fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR
129 functions return the \fBarg\fR value assigned in the corresponding set functions.
130 .PP
131 The \fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR functions return 1 on success
132 or 0 if \fBblock_size\fR is too large.
133 .PP
134 The \fBcb\fR returns the number of padding bytes to add to the record. A return of 0
135 indicates no padding will be added. A return value that causes the record to
136 exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH) will pad out to the
137 maximum record size.
138 .PP
139 The \fBSSL_CTX_get_record_padding_callback_arg()\fR function returns 1 on success or 0 if
140 the callback function is not set because Kernel TLS is configured for the SSL object.
141 .SH NOTES
142 .IX Header "NOTES"
143 The default behavior is to add no padding to the record.
144 .PP
145 A user-supplied padding callback function will override the behavior set by
146 \&\fBSSL_set_block_padding()\fR or \fBSSL_CTX_set_block_padding()\fR. Setting the user-supplied
147 callback to NULL will restore the configured block padding behavior.
148 .PP
149 These functions only apply to TLS 1.3 records being written.
150 .PP
151 Padding bytes are not added in constant-time.
152 .SH "SEE ALSO"
153 .IX Header "SEE ALSO"
154 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3)
155 .SH HISTORY
156 .IX Header "HISTORY"
157 The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1.
158 .PP
159 The return type of \fBSSL_CTX_set_record_padding_callback()\fR function was
160 changed to int in OpenSSL 3.0.
161 .PP
162 The functions \fBSSL_set_block_padding_ex()\fR and \fBSSL_CTX_set_block_padding_ex()\fR
163 were added in OpenSSL 3.4.
164 .SH COPYRIGHT
165 .IX Header "COPYRIGHT"
166 Copyright 2017\-2024 The OpenSSL Project Authors. All Rights Reserved.
167 .PP
168 Licensed under the Apache License 2.0 (the "License"). You may not use
169 this file except in compliance with the License. You can obtain a copy
170 in the file LICENSE in the source distribution or at
171 <https://www.openssl.org/source/license.html>.