Line data    Source code

       1              : /*
       2              :  *
       3              :  *    Copyright (c) 2026 Project CHIP Authors
       4              :  *    All rights reserved.
       5              :  *
       6              :  *    Licensed under the Apache License, Version 2.0 (the "License");
       7              :  *    you may not use this file except in compliance with the License.
       8              :  *    You may obtain a copy of the License at
       9              :  *
      10              :  *        http://www.apache.org/licenses/LICENSE-2.0
      11              :  *
      12              :  *    Unless required by applicable law or agreed to in writing, software
      13              :  *    distributed under the License is distributed on an "AS IS" BASIS,
      14              :  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      15              :  *    See the License for the specific language governing permissions and
      16              :  *    limitations under the License.
      17              :  */
      18              : 
      19              : /**
      20              :  *    @file
      21              :  *      Base-85 utility functions.
      22              :  *
      23              :  *      Compatible with Python's base64.b85encode / b85decode (RFC 1924 alphabet).
      24              :  *      Generally, blocks of 4 bytes are encoded into 5 characters, but arbitrary
      25              :  *      input lengths are supported via internal padding and truncation of the last block.
      26              :  *
      27              :  *      Note: Unlike Pythons b85decode, this decoder rejects non-canonical encodings.
      28              :  */
      29              : 
      30              : #pragma once
      31              : 
      32              : #include <lib/core/CHIPError.h>
      33              : #include <lib/support/CodeUtils.h>
      34              : 
      35              : #include <stddef.h>
      36              : #include <stdint.h>
      37              : 
      38              : namespace chip {
      39              : 
      40              : /**
      41              :  * Returns the decoded length for a given Base85 encoded length.
      42              :  */
      43           47 : constexpr size_t Base85DecodedLength(size_t encodedLength)
      44              : {
      45           47 :     const size_t remainder = encodedLength % 5;
      46           47 :     return (encodedLength / 5) * 4 + (remainder ? remainder - 1 : 0);
      47              : }
      48              : 
      49              : /**
      50              :  * Returns the Base85 encoded length for a given input length, or SIZE_MAX
      51              :  * if inputLength would require an encoded size longer than SIZE_MAX.
      52              :  */
      53           12 : constexpr size_t Base85EncodedLength(size_t inputLength)
      54              : {
      55           12 :     constexpr size_t maxInputLength = Base85DecodedLength(SIZE_MAX);
      56           12 :     VerifyOrReturnValue(inputLength < maxInputLength, SIZE_MAX);
      57           12 :     const size_t remainder = inputLength % 4;
      58           12 :     return (inputLength / 4) * 5 + (remainder ? remainder + 1 : 0);
      59              : }
      60              : 
      61              : /**
      62              :  * Encode bytes to a Base85 string. The output will NOT be null-terminated.
      63              :  *
      64              :  * @param src       Input bytes to encode.
      65              :  * @param srcSize   Number of input bytes.
      66              :  * @param dest      Output buffer for the encoded string.
      67              :  * @param destSize  Size of the output buffer (must be >= Base85EncodedLength(srcSize)).
      68              :  *
      69              :  * Note: src and dest must not overlap
      70              :  *
      71              :  * @retval CHIP_ERROR_BUFFER_TOO_SMALL if the output buffer is too small.
      72              :  */
      73              : CHIP_ERROR BytesToBase85(const uint8_t * src, size_t srcSize, char * dest, size_t destSize);
      74              : 
      75              : /**
      76              :  * Decode a Base85 string to bytes.
      77              :  *
      78              :  * @param src       Input Base85 string.
      79              :  * @param srcSize   Length of the input string.
      80              :  * @param dest      Output buffer for decoded bytes.
      81              :  * @param destSize  Size of the output buffer (must be >= Base85DecodedLength(srcSize)).
      82              :  *
      83              :  * Note: src and dest must not overlap, except for the special case of
      84              :  * in-place decoding (dest == src), which is supported.
      85              :  *
      86              :  * @retval CHIP_ERROR_BUFFER_TOO_SMALL if the output buffer is too small.
      87              :  * @retval CHIP_ERROR_INVALID_ARGUMENT if the input contains invalid characters, has an
      88              :  *                                     invalid length, or invalid (non-canonical) padding.
      89              :  */
      90              : CHIP_ERROR Base85ToBytes(const char * src, size_t srcSize, uint8_t * dest, size_t destSize);
      91              : 
      92              : // Legacy API compatible with Base64Encode / Base64Decode.
      93              : 
      94              : inline uint16_t Base85Encode(const uint8_t * in, uint16_t inLen, char * out)
      95              : {
      96              :     size_t outLen = Base85EncodedLength(inLen);
      97              :     VerifyOrReturnValue(outLen < UINT16_MAX && BytesToBase85(in, inLen, out, outLen) == CHIP_NO_ERROR, UINT16_MAX);
      98              :     return static_cast<uint16_t>(outLen);
      99              : }
     100              : 
     101              : inline uint16_t Base85Decode(const char * in, uint16_t inLen, uint8_t * out)
     102              : {
     103              :     size_t outLen = Base85DecodedLength(inLen);
     104              :     VerifyOrReturnValue(outLen < UINT16_MAX && Base85ToBytes(in, inLen, out, outLen) == CHIP_NO_ERROR, UINT16_MAX);
     105              :     return static_cast<uint16_t>(outLen);
     106              : }
     107              : 
     108              : inline uint32_t Base85Encode32(const uint8_t * in, uint32_t inLen, char * out)
     109              : {
     110              :     size_t outLen = Base85EncodedLength(inLen);
     111              :     VerifyOrReturnValue(outLen < UINT32_MAX && BytesToBase85(in, inLen, out, outLen) == CHIP_NO_ERROR, UINT32_MAX);
     112              :     return static_cast<uint32_t>(outLen);
     113              : }
     114              : 
     115              : inline uint32_t Base85Decode32(const char * in, uint32_t inLen, uint8_t * out)
     116              : {
     117              :     size_t outLen = Base85DecodedLength(inLen);
     118              :     VerifyOrReturnValue(outLen < UINT32_MAX && Base85ToBytes(in, inLen, out, outLen) == CHIP_NO_ERROR, UINT32_MAX);
     119              :     return static_cast<uint32_t>(outLen);
     120              : }
     121              : 
     122              : } // namespace chip