1Handling Some MAX Defines in Future
2===================================
3
4Problem Definition
5------------------
6
7The public headers contain multiple `#define` macros that limit sizes or
8numbers of various kinds. In some cases they are uncontroversial so they
9do not require any changes or workarounds for these limits. Such values
10are not discussed further in this document. This document discusses only
11some particularly problematic values and proposes some ways how to
12change or overcome these particular limits.
13
14Individual Values
15-----------------
16
17### HMAC_MAX_MD_CBLOCK
18
19**Current value:** 200
20
21This is a deprecated define which is useless. It is not used anywhere.
22
23#### Proposed solution:
24
25It should be just removed with 4.0.
26
27### EVP_MAX_MD_SIZE
28
29**Current value:** 64
30
31It is unlikely we will see longer than 512 bit hashes any time soon.
32XOF functions do not count and the XOF output length is not and should
33not be limited by this value.
34
35It is widely used throughout the codebase and by 3rd party applications.
36
37#### API calls depending on this:
38
39HMAC() - no way to specify the length of the output buffer
40
41X509_pubkey_digest() - no way to specify the length of the output buffer
42
43EVP_Q_digest() - no way to specify the length of the output buffer
44
45EVP_Digest() - no way to specify the length of the output buffer
46
47EVP_DigestFinal_ex() - this is actually documented to allow larger output
48if set explicitly by some application call that sets the output size
49
50#### Proposed solution:
51
52Keep the value as is, do not deprecate. Review the codebase if it isn't
53used in places where XOF might be used with arbitrary output length.
54
55Perhaps introduce API calls replacing the calls above that would have
56an input parameter indicating the size of the output buffer.
57
58### EVP_MAX_KEY_LENGTH
59
60**Current value:** 64
61
62This is used throughout the code and depended on in a subtle way. It can
63be assumed that 3rd party applications use this value to allocate fixed
64buffers for keys. It is unlikely that symmetric ciphers with keys longer
65than 512 bits will be used any time soon.
66
67#### API calls depending on this:
68
69EVP_KDF_CTX_get_kdf_size() returns EVP_MAX_KEY_LENGTH for KRB5KDF until
70the cipher is set.
71
72EVP_CIPHER_CTX_rand_key() - no way to specify the length of the output
73buffer.
74
75#### Proposed solution:
76
77Keep the value as is, do not deprecate. Possibly review the codebase
78to not depend on this value but there are many such cases. Avoid adding
79further APIs depending on this value.
80
81### EVP_MAX_IV_LENGTH
82
83**Current value:** 16
84
85This value is the most problematic one as in case there are ciphers with
86longer block size than 128 bits it could be potentially useful to have
87longer IVs than just 16 bytes. There are many cases throughout the code
88where fixed size arrays of EVP_MAX_IV_LENGTH are used.
89
90#### API calls depending on this:
91
92SSL_CTX_set_tlsext_ticket_key_evp_cb() explicitly uses EVP_MAX_IV_LENGTH
93in the callback function signature.
94
95SSL_CTX_set_tlsext_ticket_key_cb() is a deprecated version of the same
96and has the same problem.
97
98#### Proposed solution:
99
100Deprecate the above API call and add a replacement which explicitly
101passes the length of the _iv_ parameter.
102
103Review and modify the codebase to not depend on and use EVP_MAX_IV_LENGTH.
104
105Deprecate the EVP_MAX_IV_LENGTH macro. Avoid adding further APIs depending
106on this value.
107
108### EVP_MAX_BLOCK_LENGTH
109
110**Current value:** 32
111
112This is used in a few places in the code. It is possible that this is
113used by 3rd party applications to allocate some fixed buffers for single
114or multiple blocks. It is unlikely that symmetric ciphers with block sizes
115 longer than 256 bits will be used any time soon.
116
117#### API calls depending on this:
118
119None
120
121#### Proposed solution:
122
123Keep the value as is, do not deprecate. Possibly review the codebase
124to not depend on this value but there are many such cases. Avoid adding
125APIs depending on this value.
126
127### EVP_MAX_AEAD_TAG_LENGTH
128
129**Current value:** 16
130
131This macro is used in a single place in hpke to allocate a fixed buffer.
132The EVP_EncryptInit(3) manual page mentions the tag size being at most
13316 bytes for EVP_CIPHER_CTX_ctrl(EVP_CTRL_AEAD_SET_TAG). The value is
134problematic as for HMAC/KMAC based AEAD ciphers the tag length can be
135larger than block size. Even in case we would have block ciphers with
136256 block size the maximum tag length value of 16 is limiting.
137
138#### API calls depending on this:
139
140None (except the documentation in
141EVP_CIPHER_CTX_ctrl(EVP_CTRL_AEAD_SET/GET_TAG))
142
143#### Proposed solution:
144
145Review and modify the codebase to not depend on and use
146EVP_MAX_AEAD_TAG_LENGTH.
147
148Deprecate the EVP_MAX_AEAD_TAG_LENGTH macro. Avoid adding APIs depending
149on this value.
150