1
0

coding.h 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233
  1. /*!
  2. \ingroup Base_Encoding
  3. \brief This function decodes the given Base64 encoded input, in, and
  4. stores the result in the output buffer out. It also sets the size
  5. written to the output buffer in the variable outLen.
  6. \return 0 Returned upon successfully decoding the Base64 encoded input
  7. \return BAD_FUNC_ARG Returned if the output buffer is too small to
  8. store the decoded input
  9. \return ASN_INPUT_E Returned if a character in the input buffer falls
  10. outside of the Base64 range ([A-Za-z0-9+/=]) or if there is an invalid
  11. line ending in the Base64 encoded input
  12. \param in pointer to the input buffer to decode
  13. \param inLen length of the input buffer to decode
  14. \param out pointer to the output buffer in which to store the decoded
  15. message
  16. \param outLen pointer to the length of the output buffer. Updated with
  17. the bytes written at the end of the function call
  18. _Example_
  19. \code
  20. byte encoded[] = { // initialize text to decode };
  21. byte decoded[sizeof(encoded)];
  22. // requires at least (sizeof(encoded) * 3 + 3) / 4 room
  23. int outLen = sizeof(decoded);
  24. if( Base64_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
  25. // error decoding input buffer
  26. }
  27. \endcode
  28. \sa Base64_Encode
  29. \sa Base16_Decode
  30. */
  31. int Base64_Decode(const byte* in, word32 inLen, byte* out,
  32. word32* outLen);
  33. /*!
  34. \ingroup Base_Encoding
  35. \brief This function encodes the given input, in, and stores the Base64
  36. encoded result in the output buffer out. It writes the data with the
  37. traditional ‘\n’ line endings, instead of escaped %0A line endings. Upon
  38. successfully completing, this function also sets outLen to the number
  39. of bytes written to the output buffer.
  40. \return 0 Returned upon successfully decoding the Base64 encoded input
  41. \return BAD_FUNC_ARG Returned if the output buffer is too small to
  42. store the encoded input
  43. \return BUFFER_E Returned if the output buffer runs out of room
  44. while encoding
  45. \param in pointer to the input buffer to encode
  46. \param inLen length of the input buffer to encode
  47. \param out pointer to the output buffer in which to store the
  48. encoded message
  49. \param outLen pointer to the length of the output buffer in
  50. which to store the encoded message
  51. _Example_
  52. \code
  53. byte plain[] = { // initialize text to encode };
  54. byte encoded[MAX_BUFFER_SIZE];
  55. int outLen = sizeof(encoded);
  56. if( Base64_Encode(plain, sizeof(plain), encoded, &outLen) != 0 ) {
  57. // error encoding input buffer
  58. }
  59. \endcode
  60. \sa Base64_EncodeEsc
  61. \sa Base64_Decode
  62. */
  63. int Base64_Encode(const byte* in, word32 inLen, byte* out,
  64. word32* outLen);
  65. /*!
  66. \ingroup Base_Encoding
  67. \brief This function encodes the given input, in, and stores the
  68. Base64 encoded result in the output buffer out. It writes the data
  69. with %0A escaped line endings instead of ‘\n’ line endings.
  70. Upon successfully completing, this function also sets outLen
  71. to the number of bytes written to the output buffer.
  72. \return 0 Returned upon successfully decoding the Base64 encoded input
  73. \return BAD_FUNC_ARG Returned if the output buffer is too small
  74. to store the encoded input
  75. \return BUFFER_E Returned if the output buffer runs out of
  76. room while encoding
  77. \return ASN_INPUT_E Returned if there is an error processing
  78. the decode on the input message
  79. \param in pointer to the input buffer to encode
  80. \param inLen length of the input buffer to encode
  81. \param out pointer to the output buffer in which to store
  82. the encoded message
  83. \param outLen pointer to the length of the output buffer in
  84. which to store the encoded message
  85. _Example_
  86. \code
  87. byte plain[] = { // initialize text to encode };
  88. byte encoded[MAX_BUFFER_SIZE];
  89. int outLen = sizeof(encoded);
  90. if( Base64_EncodeEsc(plain, sizeof(plain), encoded, &outLen) != 0 ) {
  91. // error encoding input buffer
  92. }
  93. \endcode
  94. \sa Base64_Encode
  95. \sa Base64_Decode
  96. */
  97. int Base64_EncodeEsc(const byte* in, word32 inLen, byte* out,
  98. word32* outLen);
  99. /*!
  100. \ingroup Base_Encoding
  101. \brief This function encodes the given input, in, and stores the
  102. Base64 encoded result in the output buffer out. It writes the data
  103. with no new lines. Upon successfully completing, this function
  104. also sets outLen to the number of bytes written to the output buffer
  105. \return 0 Returned upon successfully decoding the Base64 encoded input
  106. \return BAD_FUNC_ARG Returned if the output buffer is too small
  107. to store the encoded input
  108. \return BUFFER_E Returned if the output buffer runs out of room
  109. while encoding
  110. \return ASN_INPUT_E Returned if there is an error processing the
  111. decode on the input message
  112. \param in pointer to the input buffer to encode
  113. \param inLen length of the input buffer to encode
  114. \param out pointer to the output buffer in which to store the
  115. encoded message
  116. \param outLen pointer to the length of the output buffer in which to
  117. store the encoded message
  118. _Example_
  119. \code
  120. byte plain[] = { // initialize text to encode };
  121. byte encoded[MAX_BUFFER_SIZE];
  122. int outLen = sizeof(encoded);
  123. if( Base64_Encode_NoNl(plain, sizeof(plain), encoded, &outLen) != 0 ) {
  124. // error encoding input buffer
  125. }
  126. \endcode
  127. \sa Base64_Encode
  128. \sa Base64_Decode
  129. */
  130. int Base64_Encode_NoNl(const byte* in, word32 inLen, byte* out,
  131. word32* outLen);
  132. /*!
  133. \ingroup Base_Encoding
  134. \brief This function decodes the given Base16 encoded input, in, and
  135. stores the result in the output buffer out. It also sets the size written
  136. to the output buffer in the variable outLen.
  137. \return 0 Returned upon successfully decoding the Base16 encoded input
  138. \return BAD_FUNC_ARG Returned if the output buffer is too small to store
  139. the decoded input or if the input length is not a multiple of two
  140. \return ASN_INPUT_E Returned if a character in the input buffer falls
  141. outside of the Base16 range ([0-9A-F])
  142. \param in pointer to the input buffer to decode
  143. \param inLen length of the input buffer to decode
  144. \param out pointer to the output buffer in which to store the decoded
  145. message
  146. \param outLen pointer to the length of the output buffer. Updated with the
  147. bytes written at the end of the function call
  148. _Example_
  149. \code
  150. byte encoded[] = { // initialize text to decode };
  151. byte decoded[sizeof(encoded)];
  152. int outLen = sizeof(decoded);
  153. if( Base16_Decode(encoded,sizeof(encoded), decoded, &outLen) != 0 ) {
  154. // error decoding input buffer
  155. }
  156. \endcode
  157. \sa Base64_Encode
  158. \sa Base64_Decode
  159. \sa Base16_Encode
  160. */
  161. int Base16_Decode(const byte* in, word32 inLen, byte* out, word32* outLen);
  162. /*!
  163. \ingroup Base_Encoding
  164. \brief Encode input to base16 output.
  165. \return 0 Success
  166. \return BAD_FUNC_ARG Returns if in, out, or outLen is null or if outLen is
  167. less than 2 times inLen plus 1.
  168. \param in Pointer to input buffer to be encoded.
  169. \param inLen Length of input buffer.
  170. \param out Pointer to output buffer.
  171. \param outLen Length of output buffer. Is set to len of encoded output.
  172. _Example_
  173. \code
  174. byte in[] = { // Contents of something to be encoded };
  175. byte out[NECESSARY_OUTPUT_SIZE];
  176. word32 outSz = sizeof(out);
  177. if(Base16_Encode(in, sizeof(in), out, &outSz) != 0)
  178. {
  179. // Handle encode error
  180. }
  181. \endcode
  182. \sa Base64_Encode
  183. \sa Base64_Decode
  184. \sa Base16_Decode
  185. */
  186. int Base16_Encode(const byte* in, word32 inLen, byte* out, word32* outLen);