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