Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/base32_requirements.md

raw
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. **]**