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