1 files changed, 57 insertions, 7 deletions
diff --git a/common/base64.h b/common/base64.h
index b53ed88f..1b341e9b 100644
--- a/common/base64.h
+++ b/common/base64.h
@@ -1,5 +1,5 @@
 /**
- * Copyright (C) 2017 Koichiro Iwao, all xrdp contributors
+ * Copyright (C) 2021 Koichiro Iwao, all xrdp contributors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,16 +17,66 @@
 /**
  * @file    common/base64.h
  * @brief   Base64 encoder / decoder
+ *
+ * Base-64 is described in RFC4648. The following notes apply to this
+ * implementation:-
+ * - The only supported characters are [A-Za-z0-9+/=]. At present,
+ *   embedded linefeeds and URL encodings are not supported.
+ *
  */
 
-#if !defined(SSL_CALLS_H)
-#define SSL_CALLS_H
+#if !defined(BASE64_CALLS_H)
+#define BASE64_CALLS_H
 
 #include "arch.h"
 
+/*
+ * Decodes a base64 string
+ *
+ * @param src Pointer to null-terminated source
+ * @param dst Pointer to output buffer
+ * @param dst_len Length of above. No more than this is written to the
+ *                output buffer
+ * @param actual_len Pointer to value to receive actual length of decoded data
+ * @return 0 for success, 1 for an invalid input string
+ *
+ * The following notes apply to this implementation:-
+ * - Embedded padding is supported, provided it only occurs at the end
+ *   of a quantum as described in RFC4648(4). This allows concatenated
+ *   encodings to be fed into the decoder.
+ * - Padding of the last quantum is assumed if not provided.
+ * - Excess padding of the last quantum is ignored.
+ *
+ * Only dst_len bytes at most are written to the output. The length
+ * returned in actual_len however represents how much buffer is needed for
+ * a correct result. This may be more than dst_len, and enables the caller
+ * to detect a potential buffer overflow
+ */
+int
+base64_decode(const char *src, char *dst, size_t dst_len, size_t *actual_len);
+
+/*
+ * Encodes a buffer as base64
+ *
+ * @param src Pointer to source
+ * @param src_len Length of above.
+ * @param dst Pointer to output buffer for null-terminated string
+ * @param dst_len Length of above. No more than this is written to the
+ *                output buffer
+ * @return Number of source characters processed
+ *
+ * The following notes apply to this implementation:-
+ * - Padding of the last quantum is always written if the number of
+ *   source bytes is not divisible by 3.
+ *
+ * The number of source characters processed is always returned. If
+ * the destination buffer is too small for all the output plus a
+ * terminator, the returned value from this procedure will be less than
+ * src_len. In this case no padding characters will have been written,
+ * and the remaining characters can be converted with more calls to
+ * this procedure.
+ */
 size_t
-base64_decoded_bytes(const char *src);
-char *
-base64_decode(char *dst, const char *src, size_t len);
+base64_encode(const char *src, size_t src_len, char *dst, size_t dst_len);
 
-#endif
+#endif /* BASE64_CALLS_H */