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