doc/man3/SSL_CTX_set_record_padding_callback.pod

   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(const SSL_CTX *ctx);
  23
  24  void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg);
  25  void *SSL_get_record_padding_callback_arg(const 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()
  57 functions return the B<arg> value assigned in the corresponding set functions.
  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 Apache License 2.0 (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