NetworkPkg: Convert files to CRLF line ending
[mirror_edk2.git] / NetworkPkg / TlsDxe / TlsImpl.h
1 /** @file\r
2   Header file of Miscellaneous Routines for TlsDxe driver.\r
3 \r
4 Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>\r
5 \r
6 This program and the accompanying materials\r
7 are licensed and made available under the terms and conditions of the BSD License\r
8 which accompanies this distribution.  The full text of the license may be found at\r
9 http://opensource.org/licenses/bsd-license.php\r
10 \r
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
13 \r
14 **/\r
15 \r
16 #ifndef __EFI_TLS_IMPL_H__\r
17 #define __EFI_TLS_IMPL_H__\r
18 \r
19 //\r
20 // Libraries\r
21 //\r
22 #include <Library/UefiBootServicesTableLib.h>\r
23 #include <Library/MemoryAllocationLib.h>\r
24 #include <Library/BaseMemoryLib.h>\r
25 #include <Library/BaseLib.h>\r
26 #include <Library/UefiLib.h>\r
27 #include <Library/DebugLib.h>\r
28 #include <Library/NetLib.h>\r
29 #include <Library/BaseCryptLib.h>\r
30 #include <Library/TlsLib.h>\r
31 \r
32 //\r
33 // Consumed Protocols\r
34 //\r
35 #include <Protocol/Tls.h>\r
36 #include <Protocol/TlsConfig.h>\r
37 \r
38 #include <IndustryStandard/Tls1.h>\r
39 \r
40 #include "TlsDriver.h"\r
41 \r
42 //\r
43 // Protocol instances\r
44 //\r
45 extern EFI_SERVICE_BINDING_PROTOCOL    mTlsServiceBinding;\r
46 extern EFI_TLS_PROTOCOL                mTlsProtocol;\r
47 extern EFI_TLS_CONFIGURATION_PROTOCOL  mTlsConfigurationProtocol;\r
48 \r
49 #define RECORD_HEADER_LEN 5 /// ContentType(1) + Version(2) + Length(2)\r
50 \r
51 #define MAX_BUFFER_SIZE   32768\r
52 \r
53 /**\r
54   Encrypt the message listed in fragment.\r
55 \r
56   @param[in]       TlsInstance    The pointer to the TLS instance.\r
57   @param[in, out]  FragmentTable  Pointer to a list of fragment.\r
58                                   On input these fragments contain the TLS header and\r
59                                   plain text TLS payload;\r
60                                   On output these fragments contain the TLS header and\r
61                                   cipher text TLS payload.\r
62   @param[in]       FragmentCount  Number of fragment.\r
63 \r
64   @retval EFI_SUCCESS             The operation completed successfully.\r
65   @retval EFI_OUT_OF_RESOURCES    Can't allocate memory resources.\r
66   @retval EFI_ABORTED             TLS session state is incorrect.\r
67   @retval Others                  Other errors as indicated.\r
68 **/\r
69 EFI_STATUS\r
70 TlsEncryptPacket (\r
71   IN     TLS_INSTANCE                  *TlsInstance,\r
72   IN OUT EFI_TLS_FRAGMENT_DATA         **FragmentTable,\r
73   IN     UINT32                        *FragmentCount\r
74   );\r
75 \r
76 /**\r
77   Decrypt the message listed in fragment.\r
78 \r
79   @param[in]       TlsInstance    The pointer to the TLS instance.\r
80   @param[in, out]  FragmentTable  Pointer to a list of fragment.\r
81                                   On input these fragments contain the TLS header and\r
82                                   cipher text TLS payload;\r
83                                   On output these fragments contain the TLS header and\r
84                                   plain text TLS payload.\r
85   @param[in]       FragmentCount  Number of fragment.\r
86 \r
87   @retval EFI_SUCCESS             The operation completed successfully.\r
88   @retval EFI_OUT_OF_RESOURCES    Can't allocate memory resources.\r
89   @retval EFI_ABORTED             TLS session state is incorrect.\r
90   @retval Others                  Other errors as indicated.\r
91 **/\r
92 EFI_STATUS\r
93 TlsDecryptPacket (\r
94   IN     TLS_INSTANCE                  *TlsInstance,\r
95   IN OUT EFI_TLS_FRAGMENT_DATA         **FragmentTable,\r
96   IN     UINT32                        *FragmentCount\r
97   );\r
98 \r
99 /**\r
100   Set TLS session data.\r
101 \r
102   The SetSessionData() function set data for a new TLS session. All session data should\r
103   be set before BuildResponsePacket() invoked.\r
104 \r
105   @param[in]  This                Pointer to the EFI_TLS_PROTOCOL instance.\r
106   @param[in]  DataType            TLS session data type.\r
107   @param[in]  Data                Pointer to session data.\r
108   @param[in]  DataSize            Total size of session data.\r
109 \r
110   @retval EFI_SUCCESS             The TLS session data is set successfully.\r
111   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:\r
112                                   This is NULL.\r
113                                   Data is NULL.\r
114                                   DataSize is 0.\r
115   @retval EFI_UNSUPPORTED         The DataType is unsupported.\r
116   @retval EFI_ACCESS_DENIED       If the DataType is one of below:\r
117                                   EfiTlsClientRandom\r
118                                   EfiTlsServerRandom\r
119                                   EfiTlsKeyMaterial\r
120   @retval EFI_NOT_READY           Current TLS session state is NOT\r
121                                   EfiTlsSessionStateNotStarted.\r
122   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.\r
123 **/\r
124 EFI_STATUS\r
125 EFIAPI\r
126 TlsSetSessionData (\r
127   IN     EFI_TLS_PROTOCOL              *This,\r
128   IN     EFI_TLS_SESSION_DATA_TYPE     DataType,\r
129   IN     VOID                          *Data,\r
130   IN     UINTN                         DataSize\r
131   );\r
132 \r
133 /**\r
134   Get TLS session data.\r
135 \r
136   The GetSessionData() function return the TLS session information.\r
137 \r
138   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.\r
139   @param[in]       DataType       TLS session data type.\r
140   @param[in, out]  Data           Pointer to session data.\r
141   @param[in, out]  DataSize       Total size of session data. On input, it means\r
142                                   the size of Data buffer. On output, it means the size\r
143                                   of copied Data buffer if EFI_SUCCESS, and means the\r
144                                   size of desired Data buffer if EFI_BUFFER_TOO_SMALL.\r
145 \r
146   @retval EFI_SUCCESS             The TLS session data is got successfully.\r
147   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:\r
148                                   This is NULL.\r
149                                   DataSize is NULL.\r
150                                   Data is NULL if *DataSize is not zero.\r
151   @retval EFI_UNSUPPORTED         The DataType is unsupported.\r
152   @retval EFI_NOT_FOUND           The TLS session data is not found.\r
153   @retval EFI_NOT_READY           The DataType is not ready in current session state.\r
154   @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.\r
155 **/\r
156 EFI_STATUS\r
157 EFIAPI\r
158 TlsGetSessionData (\r
159   IN     EFI_TLS_PROTOCOL              *This,\r
160   IN     EFI_TLS_SESSION_DATA_TYPE     DataType,\r
161   IN OUT VOID                          *Data,  OPTIONAL\r
162   IN OUT UINTN                         *DataSize\r
163   );\r
164 \r
165 /**\r
166   Build response packet according to TLS state machine. This function is only valid for\r
167   alert, handshake and change_cipher_spec content type.\r
168 \r
169   The BuildResponsePacket() function builds TLS response packet in response to the TLS\r
170   request packet specified by RequestBuffer and RequestSize. If RequestBuffer is NULL and\r
171   RequestSize is 0, and TLS session status is EfiTlsSessionNotStarted, the TLS session\r
172   will be initiated and the response packet needs to be ClientHello. If RequestBuffer is\r
173   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionClosing, the TLS\r
174   session will be closed and response packet needs to be CloseNotify. If RequestBuffer is\r
175   NULL and RequestSize is 0, and TLS session status is EfiTlsSessionError, the TLS\r
176   session has errors and the response packet needs to be Alert message based on error\r
177   type.\r
178 \r
179   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.\r
180   @param[in]       RequestBuffer  Pointer to the most recently received TLS packet. NULL\r
181                                   means TLS need initiate the TLS session and response\r
182                                   packet need to be ClientHello.\r
183   @param[in]       RequestSize    Packet size in bytes for the most recently received TLS\r
184                                   packet. 0 is only valid when RequestBuffer is NULL.\r
185   @param[out]      Buffer         Pointer to the buffer to hold the built packet.\r
186   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On input, it is\r
187                                   the buffer size provided by the caller. On output, it\r
188                                   is the buffer size in fact needed to contain the\r
189                                   packet.\r
190 \r
191   @retval EFI_SUCCESS             The required TLS packet is built successfully.\r
192   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:\r
193                                   This is NULL.\r
194                                   RequestBuffer is NULL but RequestSize is NOT 0.\r
195                                   RequestSize is 0 but RequestBuffer is NOT NULL.\r
196                                   BufferSize is NULL.\r
197                                   Buffer is NULL if *BufferSize is not zero.\r
198   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response packet.\r
199   @retval EFI_NOT_READY           Current TLS session state is NOT ready to build\r
200                                   ResponsePacket.\r
201   @retval EFI_ABORTED             Something wrong build response packet.\r
202 **/\r
203 EFI_STATUS\r
204 EFIAPI\r
205 TlsBuildResponsePacket (\r
206   IN     EFI_TLS_PROTOCOL              *This,\r
207   IN     UINT8                         *RequestBuffer, OPTIONAL\r
208   IN     UINTN                         RequestSize, OPTIONAL\r
209      OUT UINT8                         *Buffer, OPTIONAL\r
210   IN OUT UINTN                         *BufferSize\r
211   );\r
212 \r
213 /**\r
214   Decrypt or encrypt TLS packet during session. This function is only valid after\r
215   session connected and for application_data content type.\r
216 \r
217   The ProcessPacket () function process each inbound or outbound TLS APP packet.\r
218 \r
219   @param[in]       This           Pointer to the EFI_TLS_PROTOCOL instance.\r
220   @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller will take\r
221                                   responsible to handle the original FragmentTable while\r
222                                   it may be reallocated in TLS driver. If CryptMode is\r
223                                   EfiTlsEncrypt, on input these fragments contain the TLS\r
224                                   header and plain text TLS APP payload; on output these\r
225                                   fragments contain the TLS header and cipher text TLS\r
226                                   APP payload. If CryptMode is EfiTlsDecrypt, on input\r
227                                   these fragments contain the TLS header and cipher text\r
228                                   TLS APP payload; on output these fragments contain the\r
229                                   TLS header and plain text TLS APP payload.\r
230   @param[in]       FragmentCount  Number of fragment.\r
231   @param[in]       CryptMode      Crypt mode.\r
232 \r
233   @retval EFI_SUCCESS             The operation completed successfully.\r
234   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:\r
235                                   This is NULL.\r
236                                   FragmentTable is NULL.\r
237                                   FragmentCount is NULL.\r
238                                   CryptoMode is invalid.\r
239   @retval EFI_NOT_READY           Current TLS session state is NOT\r
240                                   EfiTlsSessionDataTransferring.\r
241   @retval EFI_ABORTED             Something wrong decryption the message. TLS session\r
242                                   status will become EfiTlsSessionError. The caller need\r
243                                   call BuildResponsePacket() to generate Error Alert\r
244                                   message and send it out.\r
245   @retval EFI_OUT_OF_RESOURCES    No enough resource to finish the operation.\r
246 **/\r
247 EFI_STATUS\r
248 EFIAPI\r
249 TlsProcessPacket (\r
250   IN     EFI_TLS_PROTOCOL              *This,\r
251   IN OUT EFI_TLS_FRAGMENT_DATA         **FragmentTable,\r
252   IN     UINT32                        *FragmentCount,\r
253   IN     EFI_TLS_CRYPT_MODE            CryptMode\r
254   );\r
255 \r
256 /**\r
257   Set TLS configuration data.\r
258 \r
259   The SetData() function sets TLS configuration to non-volatile storage or volatile\r
260   storage.\r
261 \r
262   @param[in]  This                Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.\r
263   @param[in]  DataType            Configuration data type.\r
264   @param[in]  Data                Pointer to configuration data.\r
265   @param[in]  DataSize            Total size of configuration data.\r
266 \r
267   @retval EFI_SUCCESS             The TLS configuration data is set successfully.\r
268   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:\r
269                                   This is NULL.\r
270                                   Data is NULL.\r
271                                   DataSize is 0.\r
272   @retval EFI_UNSUPPORTED         The DataType is unsupported.\r
273   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.\r
274 **/\r
275 EFI_STATUS\r
276 EFIAPI\r
277 TlsConfigurationSetData (\r
278   IN     EFI_TLS_CONFIGURATION_PROTOCOL  *This,\r
279   IN     EFI_TLS_CONFIG_DATA_TYPE        DataType,\r
280   IN     VOID                            *Data,\r
281   IN     UINTN                           DataSize\r
282   );\r
283 \r
284 /**\r
285   Get TLS configuration data.\r
286 \r
287   The GetData() function gets TLS configuration.\r
288 \r
289   @param[in]       This           Pointer to the EFI_TLS_CONFIGURATION_PROTOCOL instance.\r
290   @param[in]       DataType       Configuration data type.\r
291   @param[in, out]  Data           Pointer to configuration data.\r
292   @param[in, out]  DataSize       Total size of configuration data. On input, it means\r
293                                   the size of Data buffer. On output, it means the size\r
294                                   of copied Data buffer if EFI_SUCCESS, and means the\r
295                                   size of desired Data buffer if EFI_BUFFER_TOO_SMALL.\r
296 \r
297   @retval EFI_SUCCESS             The TLS configuration data is got successfully.\r
298   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:\r
299                                   This is NULL.\r
300                                   DataSize is NULL.\r
301                                   Data is NULL if *DataSize is not zero.\r
302   @retval EFI_UNSUPPORTED         The DataType is unsupported.\r
303   @retval EFI_NOT_FOUND           The TLS configuration data is not found.\r
304   @retval EFI_BUFFER_TOO_SMALL    The buffer is too small to hold the data.\r
305 **/\r
306 EFI_STATUS\r
307 EFIAPI\r
308 TlsConfigurationGetData (\r
309   IN     EFI_TLS_CONFIGURATION_PROTOCOL  *This,\r
310   IN     EFI_TLS_CONFIG_DATA_TYPE        DataType,\r
311   IN OUT VOID                            *Data, OPTIONAL\r
312   IN OUT UINTN                           *DataSize\r
313   );\r
314 \r
315 #endif\r
316 \r