Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 353 insertions, 0 deletions

diff --git a/include/iprt/base64.h b/include/iprt/base64.h
new file mode 100644
index 00000000..441f6e5e
--- /dev/null
+++ b/include/iprt/base64.h
@@ -0,0 +1,353 @@
+/** @file
+ * IPRT - Base64, MIME content transfer encoding.
+ */
+
+/*
+ * Copyright (C) 2009-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef IPRT_INCLUDED_base64_h
+#define IPRT_INCLUDED_base64_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <iprt/types.h>
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_rt_base64     RTBase64 - Base64, MIME content transfer encoding.
+ * @ingroup grp_rt
+ * @{
+ */
+
+/** @def RTBASE64_EOL_SIZE
+ * The size of the end-of-line marker. */
+#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
+# define RTBASE64_EOL_SIZE      (sizeof("\r\n") - 1)
+#else
+# define RTBASE64_EOL_SIZE      (sizeof("\n")   - 1)
+#endif
+
+
+/** @name Flags for RTBase64EncodeEx() and RTBase64EncodedLengthEx().
+ * @{ */
+/** Insert line breaks into encoded string.
+ * The size of the end-of-line marker is that that of the host platform.
+ */
+#define RTBASE64_FLAGS_EOL_NATIVE       UINT32_C(0) /**< Use native newlines. */
+#define RTBASE64_FLAGS_NO_LINE_BREAKS   UINT32_C(1) /**< No newlines.  */
+#define RTBASE64_FLAGS_EOL_LF           UINT32_C(2) /**< Use UNIX-style newlines. */
+#define RTBASE64_FLAGS_EOL_CRLF         UINT32_C(3) /**< Use DOS-style newlines. */
+#define RTBASE64_FLAGS_EOL_STYLE_MASK   UINT32_C(3) /**< End-of-line style mask. */
+/** @} */
+
+
+/**
+ * Calculates the decoded data size for a Base64 encoded string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param   pszString       The Base64 encoded string.
+ * @param   ppszEnd         If not NULL, this will point to the first char
+ *                          following the Base64 encoded text block. If
+ *                          NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedSize(const char *pszString, char **ppszEnd);
+
+/**
+ * Calculates the decoded data size for a Base64 encoded UTF-16 string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param   pwszString      The Base64 encoded UTF-16 string.
+ * @param   ppwszEnd        If not NULL, this will point to the first char
+ *                          following the Base64 encoded text block. If
+ *                          NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedUtf16Size(PCRTUTF16 pwszString, PRTUTF16 *ppwszEnd);
+
+/**
+ * Calculates the decoded data size for a Base64 encoded string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param   pszString       The Base64 encoded string.
+ * @param   cchStringMax    The max length to decode, use RTSTR_MAX if the
+ *                          length of @a pszString is not known and it is
+ *                          really zero terminated.
+ * @param   ppszEnd         If not NULL, this will point to the first char
+ *                          following the Base64 encoded text block. If
+ *                          NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedSizeEx(const char *pszString, size_t cchStringMax, char **ppszEnd);
+
+/**
+ * Calculates the decoded data size for a Base64 encoded UTF-16 string.
+ *
+ * @returns The length in bytes. -1 if the encoding is bad.
+ *
+ * @param   pwszString      The Base64 encoded UTF-16 string.
+ * @param   cwcStringMax    The max length to decode in RTUTF16 units, use
+ *                          RTSTR_MAX if the length of @a pwszString is not
+ *                          known and it is really zero terminated.
+ * @param   ppwszEnd        If not NULL, this will point to the first char
+ *                          following the Base64 encoded text block. If
+ *                          NULL the entire string is assumed to be Base64.
+ */
+RTDECL(ssize_t) RTBase64DecodedUtf16SizeEx(PCRTUTF16 pwszString, size_t cwcStringMax, PRTUTF16 *ppwszEnd);
+
+/**
+ * Decodes a Base64 encoded string into the buffer supplied by the caller.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ *          be set, nor will ppszEnd.
+ * @retval  VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param   pszString       The Base64 string. Whether the entire string or
+ *                          just the start of the string is in Base64 depends
+ *                          on whether ppszEnd is specified or not.
+ * @param   pvData          Where to store the decoded data.
+ * @param   cbData          The size of the output buffer that pvData points to.
+ * @param   pcbActual       Where to store the actual number of bytes returned.
+ *                          Optional.
+ * @param   ppszEnd         Indicates that the string may contain other stuff
+ *                          after the Base64 encoded data when not NULL. Will
+ *                          be set to point to the first char that's not part of
+ *                          the encoding. If NULL the entire string must be part
+ *                          of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64Decode(const char *pszString, void *pvData, size_t cbData, size_t *pcbActual, char **ppszEnd);
+
+/**
+ * Decodes a Base64 encoded UTF-16 string into the buffer supplied by the
+ * caller.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ *          be set, nor will ppszEnd.
+ * @retval  VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param   pwszString      The Base64 UTF-16 string. Whether the entire string
+ *                          or just the start of the string is in Base64 depends
+ *                          on whether ppwszEnd is specified or not.
+ * @param   pvData          Where to store the decoded data.
+ * @param   cbData          The size of the output buffer that pvData points to.
+ * @param   pcbActual       Where to store the actual number of bytes returned.
+ *                          Optional.
+ * @param   ppwszEnd        Indicates that the string may contain other stuff
+ *                          after the Base64 encoded data when not NULL. Will
+ *                          be set to point to the first char that's not part of
+ *                          the encoding. If NULL the entire string must be part
+ *                          of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64DecodeUtf16(PCRTUTF16 pwszString, void *pvData, size_t cbData, size_t *pcbActual, PRTUTF16 *ppwszEnd);
+
+/**
+ * Decodes a Base64 encoded string into the buffer supplied by the caller.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ *          be set, nor will ppszEnd.
+ * @retval  VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param   pszString       The Base64 string. Whether the entire string or
+ *                          just the start of the string is in Base64 depends
+ *                          on whether ppszEnd is specified or not.
+ * @param   cchStringMax    The max length to decode, use RTSTR_MAX if the
+ *                          length of @a pszString is not known and it is
+ *                          really zero terminated.
+ * @param   pvData          Where to store the decoded data.
+ * @param   cbData          The size of the output buffer that pvData points to.
+ * @param   pcbActual       Where to store the actual number of bytes returned.
+ *                          Optional.
+ * @param   ppszEnd         Indicates that the string may contain other stuff
+ *                          after the Base64 encoded data when not NULL. Will
+ *                          be set to point to the first char that's not part of
+ *                          the encoding. If NULL the entire string must be part
+ *                          of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64DecodeEx(const char *pszString, size_t cchStringMax, void *pvData, size_t cbData,
+                             size_t *pcbActual, char **ppszEnd);
+
+/**
+ * Decodes a Base64 encoded UTF-16 string into the buffer supplied by the
+ * caller.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is too small. pcbActual will not
+ *          be set, nor will ppszEnd.
+ * @retval  VERR_INVALID_BASE64_ENCODING if the encoding is wrong.
+ *
+ * @param   pwszString      The Base64 UTF-16 string. Whether the entire string
+ *                          or just the start of the string is in Base64 depends
+ *                          on whether ppszEnd is specified or not.
+ * @param   cwcStringMax    The max length to decode in RTUTF16 units, use
+ *                          RTSTR_MAX if the length of @a pwszString is not
+ *                          known and it is really zero terminated.
+ * @param   pvData          Where to store the decoded data.
+ * @param   cbData          The size of the output buffer that pvData points to.
+ * @param   pcbActual       Where to store the actual number of bytes returned.
+ *                          Optional.
+ * @param   ppwszEnd        Indicates that the string may contain other stuff
+ *                          after the Base64 encoded data when not NULL. Will
+ *                          be set to point to the first char that's not part of
+ *                          the encoding. If NULL the entire string must be part
+ *                          of the Base64 encoded data.
+ */
+RTDECL(int) RTBase64DecodeUtf16Ex(PCRTUTF16 pwszString, size_t cwcStringMax, void *pvData, size_t cbData,
+                                  size_t *pcbActual, PRTUTF16 *ppwszEnd);
+
+
+/**
+ * Calculates the length of the Base64 encoding of a given number of bytes of
+ * data produced by RTBase64Encode().
+ *
+ * @returns The Base64 string length, excluding the terminator.
+ * @param   cbData      The number of bytes to encode.
+ */
+RTDECL(size_t) RTBase64EncodedLength(size_t cbData);
+
+/**
+ * Calculates the UTF-16 length of the Base64 encoding of a given number of
+ * bytes of data produced by RTBase64EncodeUtf16().
+ *
+ * @returns The Base64 UTF-16 string length (in RTUTF16 units), excluding the
+ *          terminator.
+ * @param   cbData      The number of bytes to encode.
+ */
+RTDECL(size_t) RTBase64EncodedUtf16Length(size_t cbData);
+
+/**
+ * Calculates the length of the Base64 encoding of a given number of bytes of
+ * data produced by RTBase64EncodeEx() with the same @a fFlags.
+ *
+ * @returns The Base64 string length, excluding the terminator.
+ * @param   cbData      The number of bytes to encode.
+ * @param   fFlags      Flags, any combination of the RTBASE64_FLAGS \#defines.
+ */
+RTDECL(size_t) RTBase64EncodedLengthEx(size_t cbData, uint32_t fFlags);
+
+/**
+ * Calculates the UTF-16 length of the Base64 encoding of a given number of
+ * bytes of data produced by RTBase64EncodeUtf16Ex() with the same @a fFlags.
+ *
+ * @returns The Base64 UTF-16 string length (in RTUTF16 units), excluding the
+ *          terminator.
+ * @param   cbData      The number of bytes to encode.
+ * @param   fFlags      Flags, any combination of the RTBASE64_FLAGS \#defines.
+ */
+RTDECL(size_t) RTBase64EncodedUtf16LengthEx(size_t cbData, uint32_t fFlags);
+
+/**
+ * Encodes the specifed data into a Base64 string, the caller supplies the
+ * output buffer.
+ *
+ * This is equivalent to calling RTBase64EncodeEx() with no flags.
+ *
+ * @returns IRPT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ *          may contain an invalid Base64 string.
+ *
+ * @param   pvData      The data to encode.
+ * @param   cbData      The number of bytes to encode.
+ * @param   pszBuf      Where to put the Base64 string.
+ * @param   cbBuf       The size of the output buffer, including the terminator.
+ * @param   pcchActual  The actual number of characters returned.
+ */
+RTDECL(int) RTBase64Encode(const void *pvData, size_t cbData, char *pszBuf, size_t cbBuf, size_t *pcchActual);
+
+/**
+ * Encodes the specifed data into a Base64 UTF-16 string, the caller supplies
+ * the output buffer.
+ *
+ * This is equivalent to calling RTBase64EncodeUtf16Ex() with no flags.
+ *
+ * @returns IRPT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ *          may contain an invalid Base64 string.
+ *
+ * @param   pvData      The data to encode.
+ * @param   cbData      The number of bytes to encode.
+ * @param   pwszBuf     Where to put the Base64 UTF-16 string.
+ * @param   cwcBuf      The size of the output buffer in RTUTF16 units,
+ *                      including the terminator.
+ * @param   pcwcActual  The actual number of characters returned (excluding the
+ *                      terminator).  Optional.
+ */
+RTDECL(int) RTBase64EncodeUtf16(const void *pvData, size_t cbData, PRTUTF16 pwszBuf, size_t cwcBuf, size_t *pcwcActual);
+
+/**
+ * Encodes the specifed data into a Base64 string, the caller supplies the
+ * output buffer.
+ *
+ * @returns IRPT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ *          may contain an invalid Base64 string.
+ *
+ * @param   pvData      The data to encode.
+ * @param   cbData      The number of bytes to encode.
+ * @param   fFlags      Flags, any combination of the RTBASE64_FLAGS \#defines.
+ * @param   pszBuf      Where to put the Base64 string.
+ * @param   cbBuf       The size of the output buffer, including the terminator.
+ * @param   pcchActual  The actual number of characters returned (excluding the
+ *                      terminator).  Optional.
+ */
+RTDECL(int) RTBase64EncodeEx(const void *pvData, size_t cbData, uint32_t fFlags,
+                             char *pszBuf, size_t cbBuf, size_t *pcchActual);
+
+/**
+ * Encodes the specifed data into a Base64 UTF-16 string, the caller supplies
+ * the output buffer.
+ *
+ * @returns IRPT status code.
+ * @retval  VERR_BUFFER_OVERFLOW if the output buffer is too small. The buffer
+ *          may contain an invalid Base64 string.
+ *
+ * @param   pvData      The data to encode.
+ * @param   cbData      The number of bytes to encode.
+ * @param   fFlags      Flags, any combination of the RTBASE64_FLAGS \#defines.
+ * @param   pwszBuf     Where to put the Base64 UTF-16 string.
+ * @param   cwcBuf      The size of the output buffer in RTUTF16 units,
+ *                      including the terminator.
+ * @param   pcwcActual  The actual number of characters returned (excluding the
+ *                      terminator).  Optional.
+ */
+RTDECL(int) RTBase64EncodeUtf16Ex(const void *pvData, size_t cbData, uint32_t fFlags,
+                                  PRTUTF16 pwszBuf, size_t cwcBuf, size_t *pcwcActual);
+
+
+/** @}  */
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_base64_h */
+