secure/lib/libcrypto/man/man3/SSL_CTX_set_record_padding_callback.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_SET_RECORD_PADDING_CALLBACK 3"
 136 .TH SSL_CTX_SET_RECORD_PADDING_CALLBACK 3 "2020-04-21" "1.1.1g" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_set_record_padding_callback, SSL_set_record_padding_callback, SSL_CTX_set_record_padding_callback_arg, SSL_set_record_padding_callback_arg, SSL_CTX_get_record_padding_callback_arg, SSL_get_record_padding_callback_arg, SSL_CTX_set_block_padding, SSL_set_block_padding \- install callback to specify TLS 1.3 record padding
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
 149 \& void SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
 150 \&
 151 \& void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg);
 152 \& void *SSL_CTX_get_record_padding_callback_arg(const SSL_CTX *ctx);
 153 \&
 154 \& void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg);
 155 \& void *SSL_get_record_padding_callback_arg(const SSL *ssl);
 156 \&
 157 \& int SSL_CTX_set_block_padding(SSL_CTX *ctx, size_t block_size);
 158 \& int SSL_set_block_padding(SSL *ssl, size_t block_size);
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 \&\fBSSL_CTX_set_record_padding_callback()\fR or \fBSSL_set_record_padding_callback()\fR
 163 can be used to assign a callback function \fIcb\fR to specify the padding
 164 for \s-1TLS 1.3\s0 records. The value set in \fBctx\fR is copied to a new \s-1SSL\s0 by \fBSSL_new()\fR.
 165 .PP
 166 \&\fBSSL_CTX_set_record_padding_callback_arg()\fR and \fBSSL_set_record_padding_callback_arg()\fR
 167 assign a value \fBarg\fR that is passed to the callback when it is invoked. The value
 168 set in \fBctx\fR is copied to a new \s-1SSL\s0 by \fBSSL_new()\fR.
 169 .PP
 170 \&\fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR
 171 retrieve the \fBarg\fR value that is passed to the callback.
 172 .PP
 173 \&\fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR pads the record to a multiple
 174 of the \fBblock_size\fR. A \fBblock_size\fR of 0 or 1 disables block padding. The limit of
 175 \&\fBblock_size\fR is \s-1SSL3_RT_MAX_PLAIN_LENGTH.\s0
 176 .PP
 177 The callback is invoked for every record before encryption.
 178 The \fBtype\fR parameter is the \s-1TLS\s0 record type that is being processed; may be
 179 one of \s-1SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE,\s0 or \s-1SSL3_RT_ALERT.\s0
 180 The \fBlen\fR parameter is the current plaintext length of the record before encryption.
 181 The \fBarg\fR parameter is the value set via \fBSSL_CTX_set_record_padding_callback_arg()\fR
 182 or \fBSSL_set_record_padding_callback_arg()\fR.
 183 .SH "RETURN VALUES"
 184 .IX Header "RETURN VALUES"
 185 The \fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR
 186 functions return the \fBarg\fR value assigned in the corresponding set functions.
 187 .PP
 188 The \fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR functions return 1 on success
 189 or 0 if \fBblock_size\fR is too large.
 190 .PP
 191 The \fBcb\fR returns the number of padding bytes to add to the record. A return of 0
 192 indicates no padding will be added. A return value that causes the record to
 193 exceed the maximum record size (\s-1SSL3_RT_MAX_PLAIN_LENGTH\s0) will pad out to the
 194 maximum record size.
 195 .SH "NOTES"
 196 .IX Header "NOTES"
 197 The default behavior is to add no padding to the record.
 198 .PP
 199 A user-supplied padding callback function will override the behavior set by
 200 \&\fBSSL_set_block_padding()\fR or \fBSSL_CTX_set_block_padding()\fR. Setting the user-supplied
 201 callback to \s-1NULL\s0 will restore the configured block padding behavior.
 202 .PP
 203 These functions only apply to \s-1TLS 1.3\s0 records being written.
 204 .PP
 205 Padding bytes are not added in constant-time.
 206 .SH "SEE ALSO"
 207 .IX Header "SEE ALSO"
 208 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3)
 209 .SH "HISTORY"
 210 .IX Header "HISTORY"
 211 The record padding \s-1API\s0 was added for \s-1TLS 1.3\s0 support in OpenSSL 1.1.1.
 212 .SH "COPYRIGHT"
 213 .IX Header "COPYRIGHT"
 214 Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved.
 215 .PP
 216 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 217 this file except in compliance with the License.  You can obtain a copy
 218 in the file \s-1LICENSE\s0 in the source distribution or at
 219 <https://www.openssl.org/source/license.html>.