]>
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)); | |
19 | void SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg)); | |
20 | ||
21 | void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg); | |
22 | void *SSL_CTX_get_record_padding_callback_arg(SSL_CTX *ctx); | |
23 | ||
24 | void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg); | |
25 | void *SSL_get_record_padding_callback_arg(SSL *ssl); | |
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(). | |
35 | ||
36 | SSL_CTX_set_record_padding_callback_arg() and SSL_set_record_padding_callback_arg() | |
37 | assign a value B<arg> that is passed to the callback when it is invoked. The value | |
38 | set in B<ctx> is copied to a new SSL by SSL_new(). | |
39 | ||
40 | SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() | |
41 | retrieve the B<arg> value that is passed to the callback. | |
42 | ||
43 | SSL_CTX_set_block_padding() and SSL_set_block_padding() pads the record to a multiple | |
44 | of the B<block_size>. A B<block_size> of 0 or 1 disables block padding. The limit of | |
45 | B<block_size> is SSL3_RT_MAX_PLAIN_LENGTH. | |
46 | ||
47 | The callback is invoked for every record before encryption. | |
48 | The B<type> parameter is the TLS record type that is being processed; may be | |
49 | one of SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE, or SSL3_RT_ALERT. | |
50 | The B<len> parameter is the current plaintext length of the record before encryption. | |
51 | The B<arg> parameter is the value set via SSL_CTX_set_record_padding_callback_arg() | |
52 | or SSL_set_record_padding_callback_arg(). | |
53 | ||
54 | =head1 RETURN VALUES | |
55 | ||
56 | The SSL_CTX_get_record_padding_callback_arg() and SSL_get_record_padding_callback_arg() | |
27b138e9 | 57 | functions return the B<arg> value assigned in the corresponding set functions. |
c649d10d TS |
58 | |
59 | The SSL_CTX_set_block_padding() and SSL_set_block_padding() functions return 1 on success | |
60 | or 0 if B<block_size> is too large. | |
61 | ||
62 | The B<cb> returns the number of padding bytes to add to the record. A return of 0 | |
63 | indicates no padding will be added. A return value that causes the record to | |
64 | exceed the maximum record size (SSL3_RT_MAX_PLAIN_LENGTH) will pad out to the | |
65 | maximum record size. | |
66 | ||
67 | =head1 NOTES | |
68 | ||
69 | The default behavior is to add no padding to the record. | |
70 | ||
71 | A user-supplied padding callback function will override the behavior set by | |
72 | SSL_set_block_padding() or SSL_CTX_set_block_padding(). Setting the user-supplied | |
73 | callback to NULL will restore the configured block padding behavior. | |
74 | ||
75 | These functions only apply to TLS 1.3 records being written. | |
76 | ||
77 | Padding bytes are not added in constant-time. | |
78 | ||
79 | =head1 SEE ALSO | |
80 | ||
81 | L<ssl(7)>, L<SSL_new(3)> | |
82 | ||
83 | =head1 HISTORY | |
84 | ||
85 | The record padding API was added for TLS 1.3 support in OpenSSL 1.1.1. | |
86 | ||
87 | =head1 COPYRIGHT | |
88 | ||
89 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. | |
90 | ||
91 | Licensed under the OpenSSL license (the "License"). You may not use | |
92 | this file except in compliance with the License. You can obtain a copy | |
93 | in the file LICENSE in the source distribution or at | |
94 | L<https://www.openssl.org/source/license.html>. | |
95 | ||
96 | =cut |