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

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
   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 "2021-02-16" "1.1.1j" "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 \& int 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 Kernel \s-1TLS\s0 is not possible if the record padding callback is set, and the callback
 166 function cannot be set if Kernel \s-1TLS\s0 is already configured for the current \s-1SSL\s0 object.
 167 .PP
 168 \&\fBSSL_CTX_set_record_padding_callback_arg()\fR and \fBSSL_set_record_padding_callback_arg()\fR
 169 assign a value \fBarg\fR that is passed to the callback when it is invoked. The value
 170 set in \fBctx\fR is copied to a new \s-1SSL\s0 by \fBSSL_new()\fR.
 171 .PP
 172 \&\fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR
 173 retrieve the \fBarg\fR value that is passed to the callback.
 174 .PP
 175 \&\fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR pads the record to a multiple
 176 of the \fBblock_size\fR. A \fBblock_size\fR of 0 or 1 disables block padding. The limit of
 177 \&\fBblock_size\fR is \s-1SSL3_RT_MAX_PLAIN_LENGTH.\s0
 178 .PP
 179 The callback is invoked for every record before encryption.
 180 The \fBtype\fR parameter is the \s-1TLS\s0 record type that is being processed; may be
 181 one of \s-1SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE,\s0 or \s-1SSL3_RT_ALERT.\s0
 182 The \fBlen\fR parameter is the current plaintext length of the record before encryption.
 183 The \fBarg\fR parameter is the value set via \fBSSL_CTX_set_record_padding_callback_arg()\fR
 184 or \fBSSL_set_record_padding_callback_arg()\fR.
 185 .SH "RETURN VALUES"
 186 .IX Header "RETURN VALUES"
 187 The \fBSSL_CTX_get_record_padding_callback_arg()\fR and \fBSSL_get_record_padding_callback_arg()\fR
 188 functions return the \fBarg\fR value assigned in the corresponding set functions.
 189 .PP
 190 The \fBSSL_CTX_set_block_padding()\fR and \fBSSL_set_block_padding()\fR functions return 1 on success
 191 or 0 if \fBblock_size\fR is too large.
 192 .PP
 193 The \fBcb\fR returns the number of padding bytes to add to the record. A return of 0
 194 indicates no padding will be added. A return value that causes the record to
 195 exceed the maximum record size (\s-1SSL3_RT_MAX_PLAIN_LENGTH\s0) will pad out to the
 196 maximum record size.
 197 .PP
 198 The \fBSSL_CTX_get_record_padding_callback_arg()\fR function returns 1 on success or 0 if
 199 the callback function is not set because Kernel \s-1TLS\s0 is configured for the \s-1SSL\s0 object.
 200 .SH "NOTES"
 201 .IX Header "NOTES"
 202 The default behavior is to add no padding to the record.
 203 .PP
 204 A user-supplied padding callback function will override the behavior set by
 205 \&\fBSSL_set_block_padding()\fR or \fBSSL_CTX_set_block_padding()\fR. Setting the user-supplied
 206 callback to \s-1NULL\s0 will restore the configured block padding behavior.
 207 .PP
 208 These functions only apply to \s-1TLS 1.3\s0 records being written.
 209 .PP
 210 Padding bytes are not added in constant-time.
 211 .SH "SEE ALSO"
 212 .IX Header "SEE ALSO"
 213 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3)
 214 .SH "HISTORY"
 215 .IX Header "HISTORY"
 216 The record padding \s-1API\s0 was added for \s-1TLS 1.3\s0 support in OpenSSL 1.1.1.
 217 .PP
 218 The return type of \fBSSL_CTX_set_record_padding_callback()\fR function was
 219 changed to int in OpenSSL 3.0.
 220 .SH "COPYRIGHT"
 221 .IX Header "COPYRIGHT"
 222 Copyright 2017\-2019 The OpenSSL Project Authors. All Rights Reserved.
 223 .PP
 224 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 225 this file except in compliance with the License.  You can obtain a copy
 226 in the file \s-1LICENSE\s0 in the source distribution or at
 227 <https://www.openssl.org/source/license.html>.