1=pod
2
3=head1 NAME
4
5SSL_CTX_set_record_padding_callback,
6SSL_set_record_padding_callback,
7SSL_CTX_set_record_padding_callback_arg,
8SSL_set_record_padding_callback_arg,
9SSL_CTX_get_record_padding_callback_arg,
10SSL_get_record_padding_callback_arg,
11SSL_CTX_set_block_padding,
12SSL_CTX_set_block_padding_ex,
13SSL_set_block_padding,
14SSL_set_block_padding_ex - install callback to specify TLS 1.3 record padding
15
16=head1 SYNOPSIS
17
18 #include <openssl/ssl.h>
19
20 void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
21 int SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
22
23 void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg);
24 void *SSL_CTX_get_record_padding_callback_arg(const SSL_CTX *ctx);
25
26 void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg);
27 void *SSL_get_record_padding_callback_arg(const SSL *ssl);
28
29 int SSL_CTX_set_block_padding(SSL_CTX *ctx, size_t block_size);
30 int SSL_set_block_padding(SSL *ssl, size_t block_size);
31 int SSL_CTX_set_block_padding_ex(SSL_CTX *ctx, size_t app_block_size, size_t hs_block_size);
32 int SSL_set_block_padding_ex(SSL *ssl, size_t app_block_size, size_t hs_block_size);
33
34=head1 DESCRIPTION
35
36SSL_CTX_set_record_padding_callback() or SSL_set_record_padding_callback()
37can be used to assign a callback function I<cb> to specify the padding
38for TLS 1.3 records. The value set in B<ctx> is copied to a new SSL by SSL_new().
39Kernel TLS is not possible if the record padding callback is set, and the callback
40function cannot be set if Kernel TLS is already configured for the current SSL object.
41
42SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg()
43assign a value B<arg> that is passed to the callback when it is invoked. The value
44set in B<ctx> is copied to a new SSL by SSL_new().
45
46SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg()
47retrieve the B<arg> value that is passed to the callback.
48
49SSL_CTX_set_block_padding() and SSL_set_block_padding() pads the record to a multiple
50of the B<block_size>. A B<block_size> of 0 or 1 disables block padding. The limit of
51B<block_size> is SSL3_RT_MAX_PLAIN_LENGTH.
52
53SSL_CTX_set_block_padding_ex() and SSL_set_block_padding_ex() do similarly but
54allow the caller to separately specify the padding block size to be applied to
55handshake and application data messages.
56
57The callback is invoked for every record before encryption.
58The B<type> parameter is the TLS record type that is being processed; may be
59one of SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE, or SSL3_RT_ALERT.
60The B<len> parameter is the current plaintext length of the record before encryption.
61The B<arg> parameter is the value set via SSL_CTX_set_record_padding_callback_arg()
62or SSL_set_record_padding_callback_arg().
63
64These functions cannot be used with QUIC SSL objects.
65SSL_set_record_padding_callback() and SSL_set_block_padding() fail if called on
66a QUIC SSL object.
67
68=head1 RETURN VALUES
69
70The SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg()
71functions return the B<arg> value assigned in the corresponding set functions.
72
73The SSL_CTX_set_block_padding() and SSL_set_block_padding() functions return 1 on success
74or 0 if B<block_size> is too large.
75
76The B<cb> returns the number of padding bytes to add to the record. A return of 0
77indicates no padding will be added. A return value that causes the record to
78exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH) will pad out to the
79maximum record size.
80
81The SSL_CTX_get_record_padding_callback_arg() function returns 1 on success or 0 if
82the callback function is not set because Kernel TLS is configured for the SSL object.
83
84=head1 NOTES
85
86The default behavior is to add no padding to the record.
87
88A user-supplied padding callback function will override the behavior set by
89SSL_set_block_padding() or SSL_CTX_set_block_padding(). Setting the user-supplied
90callback to NULL will restore the configured block padding behavior.
91
92These functions only apply to TLS 1.3 records being written.
93
94Padding bytes are not added in constant-time.
95
96=head1 SEE ALSO
97
98L<ssl(7)>, L<SSL_new(3)>
99
100=head1 HISTORY
101
102The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1.
103
104The return type of SSL_CTX_set_record_padding_callback() function was
105changed to int in OpenSSL 3.0.
106
107=head1 COPYRIGHT
108
109Copyright 2017-2024 The OpenSSL Project Authors. All Rights Reserved.
110
111Licensed under the Apache License 2.0 (the "License").  You may not use
112this file except in compliance with the License.  You can obtain a copy
113in the file LICENSE in the source distribution or at
114L<https://www.openssl.org/source/license.html>.
115
116=cut
117