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