Line data    Source code

       1             : /*   SPDX-License-Identifier: BSD-3-Clause
       2             :  *   Copyright (C) 2018 Intel Corporation.
       3             :  *   All rights reserved.
       4             :  */
       5             : 
       6             : /**
       7             :  * \file
       8             :  * Base64 utility functions
       9             :  */
      10             : 
      11             : #ifndef SPDK_BASE64_H
      12             : #define SPDK_BASE64_H
      13             : 
      14             : #include "spdk/stdinc.h"
      15             : 
      16             : #ifdef __cplusplus
      17             : extern "C" {
      18             : #endif
      19             : 
      20             : /**
      21             :  * Following the Base64 part in RFC4648:
      22             :  * https://tools.ietf.org/html/rfc4648.html
      23             :  */
      24             : 
      25             : /**
      26             :  * Calculate strlen of encoded Base64 string based on raw buffer length.
      27             :  *
      28             :  * \param raw_len Length of raw buffer.
      29             :  * \return Encoded Base64 string length, excluding the terminating null byte ('\0').
      30             :  */
      31           4 : static inline size_t spdk_base64_get_encoded_strlen(size_t raw_len)
      32             : {
      33           4 :         return (raw_len + 2) / 3 * 4;
      34             : }
      35             : 
      36             : /**
      37             :  * Calculate length of raw buffer based on strlen of encoded Base64.
      38             :  *
      39             :  * This length will be the max possible decoded len. The exact decoded length could be
      40             :  * shorter depending on if there was padding in the Base64 string.
      41             :  *
      42             :  * \param encoded_strlen Length of encoded Base64 string, excluding terminating null
      43             :  * byte ('\0').
      44             :  * \return Length of raw buffer.
      45             :  */
      46          31 : static inline size_t spdk_base64_get_decoded_len(size_t encoded_strlen)
      47             : {
      48             :         /* text_strlen and raw_len should be (4n,3n), (4n+2, 3n+1) or (4n+3, 3n+2) */
      49          31 :         return encoded_strlen / 4 * 3 + ((encoded_strlen % 4 + 1) / 2);
      50             : }
      51             : 
      52             : /**
      53             :  * Base 64 Encoding with Standard Base64 Alphabet defined in RFC4684.
      54             :  *
      55             :  * \param dst Buffer address of encoded Base64 string. Its length should be enough
      56             :  * to contain Base64 string and the terminating null byte ('\0'), so it needs to be at
      57             :  * least as long as 1 + spdk_base64_get_encoded_strlen(src_len).
      58             :  * \param src Raw data buffer to be encoded.
      59             :  * \param src_len Length of raw data buffer.
      60             :  *
      61             :  * \return 0 on success.
      62             :  * \return -EINVAL if dst or src is NULL, or binary_len <= 0.
      63             :  */
      64             : int spdk_base64_encode(char *dst, const void *src, size_t src_len);
      65             : 
      66             : /**
      67             :  * Base 64 Encoding with URL and Filename Safe Alphabet.
      68             :  *
      69             :  * \param dst Buffer address of encoded Base64 string. Its length should be enough
      70             :  * to contain Base64 string and the terminating null byte ('\0'), so it needs to be at
      71             :  * least as long as 1 + spdk_base64_get_encoded_strlen(src_len).
      72             :  * \param src Raw data buffer to be encoded.
      73             :  * \param src_len Length of raw data buffer.
      74             :  *
      75             :  * \return 0 on success.
      76             :  * \return -EINVAL if dst or src is NULL, or binary_len <= 0.
      77             :  */
      78             : int spdk_base64_urlsafe_encode(char *dst, const void *src, size_t src_len);
      79             : 
      80             : /**
      81             :  * Base 64 Decoding with Standard Base64 Alphabet defined in RFC4684.
      82             :  *
      83             :  * \param dst Buffer address of decoded raw data. Its length should be enough
      84             :  * to contain decoded raw data, so it needs to be at least as long as
      85             :  * spdk_base64_get_decoded_len(encoded_strlen). If NULL, only dst_len will be populated
      86             :  * indicating the exact decoded length.
      87             :  * \param dst_len Output parameter for the length of actual decoded raw data.
      88             :  * If NULL, the actual decoded length won't be returned.
      89             :  * \param src Data buffer for base64 string to be decoded.
      90             :  *
      91             :  * \return 0 on success.
      92             :  * \return -EINVAL if src is NULL, or content of src is illegal.
      93             :  */
      94             : int spdk_base64_decode(void *dst, size_t *dst_len, const char *src);
      95             : 
      96             : /**
      97             :  * Base 64 Decoding with URL and Filename Safe Alphabet.
      98             :  *
      99             :  * \param dst Buffer address of decoded raw data. Its length should be enough
     100             :  * to contain decoded raw data, so it needs to be at least as long as
     101             :  * spdk_base64_get_decoded_len(encoded_strlen). If NULL, only dst_len will be populated
     102             :  * indicating the exact decoded length.
     103             :  * \param dst_len Output parameter for the length of actual decoded raw data.
     104             :  * If NULL, the actual decoded length won't be returned.
     105             :  * \param src Data buffer for base64 string to be decoded.
     106             :  *
     107             :  * \return 0 on success.
     108             :  * \return -EINVAL if src is NULL, or content of src is illegal.
     109             :  */
     110             : int spdk_base64_urlsafe_decode(void *dst, size_t *dst_len, const char *src);
     111             : 
     112             : #ifdef __cplusplus
     113             : }
     114             : #endif
     115             : 
     116             : #endif /* SPDK_BASE64_H */