| 1 |
# Base32 Requirements |
| 2 |
|
| 3 |
================ |
| 4 |
|
| 5 |
## Overview |
| 6 |
|
| 7 |
This module is used to encode an array of unsigned chars using the standard base32 encoding stream. |
| 8 |
|
| 9 |
## References |
| 10 |
|
| 11 |
[IETF RFC 4648](https://tools.ietf.org/html/rfc4648) |
| 12 |
|
| 13 |
## Exposed API |
| 14 |
|
| 15 |
```c |
| 16 |
extern STRING_HANDLE Azure_Base32_Encode(BUFFER_HANDLE input); |
| 17 |
extern char* Azure_Base32_Encode_Bytes(const unsigned char* source, size_t size); |
| 18 |
BUFFER_HANDLE Azure_Base32_Decode(STRING_HANDLE handle); |
| 19 |
BUFFER_HANDLE Azure_Base32_Decode_String(const char* source); |
| 20 |
``` |
| 21 |
|
| 22 |
### Azure_Base32_Encode |
| 23 |
|
| 24 |
```c |
| 25 |
extern STRING_HANDLE Azure_Base32_Encode(BUFFER_HANDLE source); |
| 26 |
``` |
| 27 |
|
| 28 |
**SRS_BASE32_07_001: [** If `source` is NULL `Azure_Base32_Encode` shall return NULL. **]** |
| 29 |
|
| 30 |
**SRS_BASE32_07_002: [** If successful `Azure_Base32_Encode` shall return the base32 value of source. **]** |
| 31 |
|
| 32 |
**SRS_BASE32_07_015: [** If `source` length is 0 `Azure_Base32_Encode` shall return an empty string. **]** |
| 33 |
|
| 34 |
**SRS_BASE32_07_003: [** `Azure_Base32_Encode` shall call into `Base32_Encode_impl` to encode the source data. **]** |
| 35 |
|
| 36 |
**SRS_BASE32_07_013: [** `Azure_Base32_Encode` shall wrap the `Base32_Encode_impl` result into a `STRING_HANDLE`. **]** |
| 37 |
|
| 38 |
**SRS_BASE32_07_014: [** Upon failure `Azure_Base32_Encode` shall return NULL. **]** |
| 39 |
|
| 40 |
### Azure_Base32_Encode_Bytes |
| 41 |
|
| 42 |
```c |
| 43 |
extern char* Azure_Base32_Encode_Bytes(const unsigned char* source, size_t size); |
| 44 |
``` |
| 45 |
|
| 46 |
**SRS_BASE32_07_004: [** If `source` is NULL `Azure_Base32_Encode_Bytes` shall return NULL. **]** |
| 47 |
|
| 48 |
**SRS_BASE32_07_005: [** If `size` is 0 `Azure_Base32_Encode_Bytes` shall return an empty string. **]** |
| 49 |
|
| 50 |
**SRS_BASE32_07_006: [** If successful `Azure_Base32_Encode_Bytes` shall return the base32 value of input. **]** |
| 51 |
|
| 52 |
**SRS_BASE32_07_007: [** `Azure_Base32_Encode_Bytes` shall call into `Base32_Encode_impl` to encode the source data. **]** |
| 53 |
|
| 54 |
**SRS_BASE32_07_014: [** Upon failure `Azure_Base32_Encode_Bytes` shall return NULL. **]** |
| 55 |
|
| 56 |
### base32_encode_impl |
| 57 |
|
| 58 |
```c |
| 59 |
static char* base32_encode_impl(const unsigned char* source, size_t src_size) |
| 60 |
``` |
| 61 |
|
| 62 |
**SRS_BASE32_07_009: [** `base32_encode_impl` shall allocate the buffer to the size of the encoding value. **]** |
| 63 |
|
| 64 |
**SRS_BASE32_07_010: [** `base32_encode_impl` shall look through `source` and separate each block into 5 bit chunks **]** |
| 65 |
|
| 66 |
**SRS_BASE32_07_011: [** `base32_encode_impl` shall then map the 5 bit chunks into one of the BASE32 values (a-z,2,3,4,5,6,7) values. **]** |
| 67 |
|
| 68 |
**SRS_BASE32_07_012: [** If the `src_size` is not divisible by 8 and less than the 40-bits, `base32_encode_impl` shall pad the remaining places with `=`. **]** |
| 69 |
|
| 70 |
### Azure_Base32_Decode_String |
| 71 |
|
| 72 |
```c |
| 73 |
extern BUFFER_HANDLE Azure_Base32_Decode_String(const char* source); |
| 74 |
``` |
| 75 |
|
| 76 |
**SRS_BASE32_07_008: [** If source is NULL `Azure_Base32_Decode_String` shall return NULL. **]** |
| 77 |
|
| 78 |
**SRS_BASE32_07_019: [** On success `Azure_Base32_Decode_String` shall return a BUFFER_HANDLE that contains the decoded bytes for source. **]** |
| 79 |
|
| 80 |
**SRS_BASE32_07_020: [** `Azure_Base32_Decode_String` shall call `base32_decode_impl` to decode the base64 value. **]** |
| 81 |
|
| 82 |
### Azure_Base32_Decode |
| 83 |
|
| 84 |
```c |
| 85 |
extern BUFFER_HANDLE Azure_Base32_Decode(STRING_HANDLE source); |
| 86 |
``` |
| 87 |
|
| 88 |
**SRS_BASE32_07_016: [** If source is NULL `Azure_Base32_Decode` shall return NULL. **]** |
| 89 |
|
| 90 |
**SRS_BASE32_07_017: [** On success `Azure_Base32_Decode` shall return a `BUFFER_HANDLE` that contains the decoded bytes for source. **]** |
| 91 |
|
| 92 |
**SRS_BASE32_07_018: [** `Azure_Base32_Decode` shall call `base32_decode_impl` to decode the base64 value **]** |
| 93 |
|
| 94 |
**SRS_BASE32_07_027: [** If the string in source value is NULL, `Azure_Base32_Decode` shall return NULL. **]** |
| 95 |
|
| 96 |
### base32_decode_impl |
| 97 |
|
| 98 |
```c |
| 99 |
static BUFFER_HANDLE base32_decode_impl(const char* source) |
| 100 |
``` |
| 101 |
|
| 102 |
**SRS_BASE32_07_021: [** If the source length is not evenly divisible by 8, `base32_decode_impl` shall return NULL. **]** |
| 103 |
|
| 104 |
**SRS_BASE32_07_022: [** `base32_decode_impl` shall allocate a temp buffer to store the in process value. **]** |
| 105 |
|
| 106 |
**SRS_BASE32_07_023: [** If an error is encountered, `base32_decode_impl` shall return NULL. **]** |
| 107 |
|
| 108 |
**SRS_BASE32_07_024: [** `base32_decode_impl` shall loop through and collect 8 characters from the source variable. **]** |
| 109 |
|
| 110 |
**SRS_BASE32_07_025: [** `base32_decode_impl` shall group 5 bytes at a time into the temp buffer. **]** |
| 111 |
|
| 112 |
**SRS_BASE32_07_026: [** Once `base32_decode_impl` is complete it shall create a BUFFER with the temp buffer. **]** |