secure/lib/libcrypto/man/SSL_CTX_set_record_padding_callback.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_SET_RECORD_PADDING_CALLBACK 3"
 132 .TH SSL_CTX_SET_RECORD_PADDING_CALLBACK 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& void SSL_CTX_set_record_padding_callback(SSL_CTX *ctx, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
 145 \& void SSL_set_record_padding_callback(SSL *ssl, size_t (*cb)(SSL *s, int type, size_t len, void *arg));
 146 \&
 147 \& void SSL_CTX_set_record_padding_callback_arg(SSL_CTX *ctx, void *arg);
 148 \& void *SSL_CTX_get_record_padding_callback_arg(SSL_CTX *ctx);
 149 \&
 150 \& void SSL_set_record_padding_callback_arg(SSL *ssl, void *arg);
 151 \& void *SSL_get_record_padding_callback_arg(SSL *ssl);
 152 \&
 153 \& int SSL_CTX_set_block_padding(SSL_CTX *ctx, size_t block_size);
 154 \& int SSL_set_block_padding(SSL *ssl, size_t block_size);
 155 .Ve
 156 .SH "DESCRIPTION"
 157 .IX Header "DESCRIPTION"
 158 \&\fISSL_CTX_set_record_padding_callback()\fR or \fISSL_set_record_padding_callback()\fR
 159 can be used to assign a callback function \fIcb\fR to specify the padding
 160 for \s-1TLS 1.3\s0 records. The value set in \fBctx\fR is copied to a new \s-1SSL\s0 by \fISSL_new()\fR.
 161 .PP
 162 \&\fISSL_CTX_set_record_padding_callback_arg()\fR and \fISSL_set_record_padding_callback_arg()\fR
 163 assign a value \fBarg\fR that is passed to the callback when it is invoked. The value
 164 set in \fBctx\fR is copied to a new \s-1SSL\s0 by \fISSL_new()\fR.
 165 .PP
 166 \&\fISSL_CTX_get_record_padding_callback_arg()\fR and \fISSL_get_record_padding_callback_arg()\fR
 167 retrieve the \fBarg\fR value that is passed to the callback.
 168 .PP
 169 \&\fISSL_CTX_set_block_padding()\fR and \fISSL_set_block_padding()\fR pads the record to a multiple
 170 of the \fBblock_size\fR. A \fBblock_size\fR of 0 or 1 disables block padding. The limit of
 171 \&\fBblock_size\fR is \s-1SSL3_RT_MAX_PLAIN_LENGTH.\s0
 172 .PP
 173 The callback is invoked for every record before encryption.
 174 The \fBtype\fR parameter is the \s-1TLS\s0 record type that is being processed; may be
 175 one of \s-1SSL3_RT_APPLICATION_DATA, SSL3_RT_HANDSHAKE,\s0 or \s-1SSL3_RT_ALERT.\s0
 176 The \fBlen\fR parameter is the current plaintext length of the record before encryption.
 177 The \fBarg\fR parameter is the value set via \fISSL_CTX_set_record_padding_callback_arg()\fR
 178 or \fISSL_set_record_padding_callback_arg()\fR.
 179 .SH "RETURN VALUES"
 180 .IX Header "RETURN VALUES"
 181 The \fISSL_CTX_get_record_padding_callback_arg()\fR and \fISSL_get_record_padding_callback_arg()\fR
 182 functions return the \fBarg\fR value assigned in the corresponding set functions.
 183 .PP
 184 The \fISSL_CTX_set_block_padding()\fR and \fISSL_set_block_padding()\fR functions return 1 on success
 185 or 0 if \fBblock_size\fR is too large.
 186 .PP
 187 The \fBcb\fR returns the number of padding bytes to add to the record. A return of 0
 188 indicates no padding will be added. A return value that causes the record to
 189 exceed the maximum record size (\s-1SSL3_RT_MAX_PLAIN_LENGTH\s0) will pad out to the
 190 maximum record size.
 191 .SH "NOTES"
 192 .IX Header "NOTES"
 193 The default behavior is to add no padding to the record.
 194 .PP
 195 A user-supplied padding callback function will override the behavior set by
 196 \&\fISSL_set_block_padding()\fR or \fISSL_CTX_set_block_padding()\fR. Setting the user-supplied
 197 callback to \s-1NULL\s0 will restore the configured block padding behavior.
 198 .PP
 199 These functions only apply to \s-1TLS 1.3\s0 records being written.
 200 .PP
 201 Padding bytes are not added in constant-time.
 202 .SH "SEE ALSO"
 203 .IX Header "SEE ALSO"
 204 \&\fIssl\fR\|(7), \fISSL_new\fR\|(3)
 205 .SH "HISTORY"
 206 .IX Header "HISTORY"
 207 The record padding \s-1API\s0 was added for \s-1TLS 1.3\s0 support in OpenSSL 1.1.1.
 208 .SH "COPYRIGHT"
 209 .IX Header "COPYRIGHT"
 210 Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
 211 .PP
 212 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 213 this file except in compliance with the License.  You can obtain a copy
 214 in the file \s-1LICENSE\s0 in the source distribution or at
 215 <https://www.openssl.org/source/license.html>.