TlsLib.h@ 105681

Last change on this file since 105681 was 99404, checked in by vboxsync, 2 years ago
Devices/EFI/FirmwareNew: Update to edk2-stable202302 and make it build, bugref:4643
Property svn:eol-style set to `native`
File size: 27.5 KB

Line
1	/** @file
2	Defines TLS Library APIs.
3
4	Copyright (c) 2016 - 2017, Intel Corporation. All rights reserved.<BR>
5	SPDX-License-Identifier: BSD-2-Clause-Patent
6
7	**/
8
9	#ifndef __TLS_LIB_H__
10	#define __TLS_LIB_H__
11
12	/**
13	Initializes the OpenSSL library.
14
15	This function registers ciphers and digests used directly and indirectly
16	by SSL/TLS, and initializes the readable error messages.
17	This function must be called before any other action takes places.
18
19	@retval TRUE The OpenSSL library has been initialized.
20	@retval FALSE Failed to initialize the OpenSSL library.
21
22	**/
23	BOOLEAN
24	EFIAPI
25	TlsInitialize (
26	VOID
27	);
28
29	/**
30	Free an allocated SSL_CTX object.
31
32	@param[in] TlsCtx Pointer to the SSL_CTX object to be released.
33
34	**/
35	VOID
36	EFIAPI
37	TlsCtxFree (
38	IN VOID *TlsCtx
39	);
40
41	/**
42	Creates a new SSL_CTX object as framework to establish TLS/SSL enabled
43	connections.
44
45	@param[in] MajorVer Major Version of TLS/SSL Protocol.
46	@param[in] MinorVer Minor Version of TLS/SSL Protocol.
47
48	@return Pointer to an allocated SSL_CTX object.
49	If the creation failed, TlsCtxNew() returns NULL.
50
51	**/
52	VOID *
53	EFIAPI
54	TlsCtxNew (
55	IN UINT8 MajorVer,
56	IN UINT8 MinorVer
57	);
58
59	/**
60	Free an allocated TLS object.
61
62	This function removes the TLS object pointed to by Tls and frees up the
63	allocated memory. If Tls is NULL, nothing is done.
64
65	@param[in] Tls Pointer to the TLS object to be freed.
66
67	**/
68	VOID
69	EFIAPI
70	TlsFree (
71	IN VOID *Tls
72	);
73
74	/**
75	Create a new TLS object for a connection.
76
77	This function creates a new TLS object for a connection. The new object
78	inherits the setting of the underlying context TlsCtx: connection method,
79	options, verification setting.
80
81	@param[in] TlsCtx Pointer to the SSL_CTX object.
82
83	@return Pointer to an allocated SSL object.
84	If the creation failed, TlsNew() returns NULL.
85
86	**/
87	VOID *
88	EFIAPI
89	TlsNew (
90	IN VOID *TlsCtx
91	);
92
93	/**
94	Checks if the TLS handshake was done.
95
96	This function will check if the specified TLS handshake was done.
97
98	@param[in] Tls Pointer to the TLS object for handshake state checking.
99
100	@retval TRUE The TLS handshake was done.
101	@retval FALSE The TLS handshake was not done.
102
103	**/
104	BOOLEAN
105	EFIAPI
106	TlsInHandshake (
107	IN VOID *Tls
108	);
109
110	/**
111	Perform a TLS/SSL handshake.
112
113	This function will perform a TLS/SSL handshake.
114
115	@param[in] Tls Pointer to the TLS object for handshake operation.
116	@param[in] BufferIn Pointer to the most recently received TLS Handshake packet.
117	@param[in] BufferInSize Packet size in bytes for the most recently received TLS
118	Handshake packet.
119	@param[out] BufferOut Pointer to the buffer to hold the built packet.
120	@param[in, out] BufferOutSize Pointer to the buffer size in bytes. On input, it is
121	the buffer size provided by the caller. On output, it
122	is the buffer size in fact needed to contain the
123	packet.
124
125	@retval EFI_SUCCESS The required TLS packet is built successfully.
126	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
127	Tls is NULL.
128	BufferIn is NULL but BufferInSize is NOT 0.
129	BufferInSize is 0 but BufferIn is NOT NULL.
130	BufferOutSize is NULL.
131	BufferOut is NULL if *BufferOutSize is not zero.
132	@retval EFI_BUFFER_TOO_SMALL BufferOutSize is too small to hold the response packet.
133	@retval EFI_ABORTED Something wrong during handshake.
134
135	**/
136	EFI_STATUS
137	EFIAPI
138	TlsDoHandshake (
139	IN VOID *Tls,
140	IN UINT8 *BufferIn OPTIONAL,
141	IN UINTN BufferInSize OPTIONAL,
142	OUT UINT8 *BufferOut OPTIONAL,
143	IN OUT UINTN *BufferOutSize
144	);
145
146	/**
147	Handle Alert message recorded in BufferIn. If BufferIn is NULL and BufferInSize is zero,
148	TLS session has errors and the response packet needs to be Alert message based on error type.
149
150	@param[in] Tls Pointer to the TLS object for state checking.
151	@param[in] BufferIn Pointer to the most recently received TLS Alert packet.
152	@param[in] BufferInSize Packet size in bytes for the most recently received TLS
153	Alert packet.
154	@param[out] BufferOut Pointer to the buffer to hold the built packet.
155	@param[in, out] BufferOutSize Pointer to the buffer size in bytes. On input, it is
156	the buffer size provided by the caller. On output, it
157	is the buffer size in fact needed to contain the
158	packet.
159
160	@retval EFI_SUCCESS The required TLS packet is built successfully.
161	@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
162	Tls is NULL.
163	BufferIn is NULL but BufferInSize is NOT 0.
164	BufferInSize is 0 but BufferIn is NOT NULL.
165	BufferOutSize is NULL.
166	BufferOut is NULL if *BufferOutSize is not zero.
167	@retval EFI_ABORTED An error occurred.
168	@retval EFI_BUFFER_TOO_SMALL BufferOutSize is too small to hold the response packet.
169
170	**/
171	EFI_STATUS
172	EFIAPI
173	TlsHandleAlert (
174	IN VOID *Tls,
175	IN UINT8 *BufferIn OPTIONAL,
176	IN UINTN BufferInSize OPTIONAL,
177	OUT UINT8 *BufferOut OPTIONAL,
178	IN OUT UINTN *BufferOutSize
179	);
180
181	/**
182	Build the CloseNotify packet.
183
184	@param[in] Tls Pointer to the TLS object for state checking.
185	@param[in, 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	Tls is NULL.
194	BufferSize is NULL.
195	Buffer is NULL if *BufferSize is not zero.
196	@retval EFI_BUFFER_TOO_SMALL BufferSize is too small to hold the response packet.
197
198	**/
199	EFI_STATUS
200	EFIAPI
201	TlsCloseNotify (
202	IN VOID *Tls,
203	IN OUT UINT8 *Buffer,
204	IN OUT UINTN *BufferSize
205	);
206
207	/**
208	Attempts to read bytes from one TLS object and places the data in Buffer.
209
210	This function will attempt to read BufferSize bytes from the TLS object
211	and places the data in Buffer.
212
213	@param[in] Tls Pointer to the TLS object.
214	@param[in,out] Buffer Pointer to the buffer to store the data.
215	@param[in] BufferSize The size of Buffer in bytes.
216
217	@retval >0 The amount of data successfully read from the TLS object.
218	@retval <=0 No data was successfully read.
219
220	**/
221	INTN
222	EFIAPI
223	TlsCtrlTrafficOut (
224	IN VOID *Tls,
225	IN OUT VOID *Buffer,
226	IN UINTN BufferSize
227	);
228
229	/**
230	Attempts to write data from the buffer to TLS object.
231
232	This function will attempt to write BufferSize bytes data from the Buffer
233	to the TLS object.
234
235	@param[in] Tls Pointer to the TLS object.
236	@param[in] Buffer Pointer to the data buffer.
237	@param[in] BufferSize The size of Buffer in bytes.
238
239	@retval >0 The amount of data successfully written to the TLS object.
240	@retval <=0 No data was successfully written.
241
242	**/
243	INTN
244	EFIAPI
245	TlsCtrlTrafficIn (
246	IN VOID *Tls,
247	IN VOID *Buffer,
248	IN UINTN BufferSize
249	);
250
251	/**
252	Attempts to read bytes from the specified TLS connection into the buffer.
253
254	This function tries to read BufferSize bytes data from the specified TLS
255	connection into the Buffer.
256
257	@param[in] Tls Pointer to the TLS connection for data reading.
258	@param[in,out] Buffer Pointer to the data buffer.
259	@param[in] BufferSize The size of Buffer in bytes.
260
261	@retval >0 The read operation was successful, and return value is the
262	number of bytes actually read from the TLS connection.
263	@retval <=0 The read operation was not successful.
264
265	**/
266	INTN
267	EFIAPI
268	TlsRead (
269	IN VOID *Tls,
270	IN OUT VOID *Buffer,
271	IN UINTN BufferSize
272	);
273
274	/**
275	Attempts to write data to a TLS connection.
276
277	This function tries to write BufferSize bytes data from the Buffer into the
278	specified TLS connection.
279
280	@param[in] Tls Pointer to the TLS connection for data writing.
281	@param[in] Buffer Pointer to the data buffer.
282	@param[in] BufferSize The size of Buffer in bytes.
283
284	@retval >0 The write operation was successful, and return value is the
285	number of bytes actually written to the TLS connection.
286	@retval <=0 The write operation was not successful.
287
288	**/
289	INTN
290	EFIAPI
291	TlsWrite (
292	IN VOID *Tls,
293	IN VOID *Buffer,
294	IN UINTN BufferSize
295	);
296
297	/**
298	Shutdown a TLS connection.
299
300	Shutdown the TLS connection without releasing the resources, meaning a new
301	connection can be started without calling TlsNew() and without setting
302	certificates etc.
303
304	@param[in] Tls Pointer to the TLS object to shutdown.
305
306	@retval EFI_SUCCESS The TLS is shutdown successfully.
307	@retval EFI_INVALID_PARAMETER Tls is NULL.
308	@retval EFI_PROTOCOL_ERROR Some other error occurred.
309	**/
310	EFI_STATUS
311	EFIAPI
312	TlsShutdown (
313	IN VOID *Tls
314	);
315
316	/**
317	Set a new TLS/SSL method for a particular TLS object.
318
319	This function sets a new TLS/SSL method for a particular TLS object.
320
321	@param[in] Tls Pointer to a TLS object.
322	@param[in] MajorVer Major Version of TLS/SSL Protocol.
323	@param[in] MinorVer Minor Version of TLS/SSL Protocol.
324
325	@retval EFI_SUCCESS The TLS/SSL method was set successfully.
326	@retval EFI_INVALID_PARAMETER The parameter is invalid.
327	@retval EFI_UNSUPPORTED Unsupported TLS/SSL method.
328
329	**/
330	EFI_STATUS
331	EFIAPI
332	TlsSetVersion (
333	IN VOID *Tls,
334	IN UINT8 MajorVer,
335	IN UINT8 MinorVer
336	);
337
338	/**
339	Set TLS object to work in client or server mode.
340
341	This function prepares a TLS object to work in client or server mode.
342
343	@param[in] Tls Pointer to a TLS object.
344	@param[in] IsServer Work in server mode.
345
346	@retval EFI_SUCCESS The TLS/SSL work mode was set successfully.
347	@retval EFI_INVALID_PARAMETER The parameter is invalid.
348	@retval EFI_UNSUPPORTED Unsupported TLS/SSL work mode.
349
350	**/
351	EFI_STATUS
352	EFIAPI
353	TlsSetConnectionEnd (
354	IN VOID *Tls,
355	IN BOOLEAN IsServer
356	);
357
358	/**
359	Set the ciphers list to be used by the TLS object.
360
361	This function sets the ciphers for use by a specified TLS object.
362
363	@param[in] Tls Pointer to a TLS object.
364	@param[in] CipherId Array of UINT16 cipher identifiers. Each UINT16
365	cipher identifier comes from the TLS Cipher Suite
366	Registry of the IANA, interpreting Byte1 and Byte2
367	in network (big endian) byte order.
368	@param[in] CipherNum The number of cipher in the list.
369
370	@retval EFI_SUCCESS The ciphers list was set successfully.
371	@retval EFI_INVALID_PARAMETER The parameter is invalid.
372	@retval EFI_UNSUPPORTED No supported TLS cipher was found in CipherId.
373	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.
374
375	**/
376	EFI_STATUS
377	EFIAPI
378	TlsSetCipherList (
379	IN VOID *Tls,
380	IN UINT16 *CipherId,
381	IN UINTN CipherNum
382	);
383
384	/**
385	Set the compression method for TLS/SSL operations.
386
387	This function handles TLS/SSL integrated compression methods.
388
389	@param[in] CompMethod The compression method ID.
390
391	@retval EFI_SUCCESS The compression method for the communication was
392	set successfully.
393	@retval EFI_UNSUPPORTED Unsupported compression method.
394
395	**/
396	EFI_STATUS
397	EFIAPI
398	TlsSetCompressionMethod (
399	IN UINT8 CompMethod
400	);
401
402	/**
403	Set peer certificate verification mode for the TLS connection.
404
405	This function sets the verification mode flags for the TLS connection.
406
407	@param[in] Tls Pointer to the TLS object.
408	@param[in] VerifyMode A set of logically or'ed verification mode flags.
409
410	**/
411	VOID
412	EFIAPI
413	TlsSetVerify (
414	IN VOID *Tls,
415	IN UINT32 VerifyMode
416	);
417
418	/**
419	Set the specified host name to be verified.
420
421	@param[in] Tls Pointer to the TLS object.
422	@param[in] Flags The setting flags during the validation.
423	@param[in] HostName The specified host name to be verified.
424
425	@retval EFI_SUCCESS The HostName setting was set successfully.
426	@retval EFI_INVALID_PARAMETER The parameter is invalid.
427	@retval EFI_ABORTED Invalid HostName setting.
428
429	**/
430	EFI_STATUS
431	EFIAPI
432	TlsSetVerifyHost (
433	IN VOID *Tls,
434	IN UINT32 Flags,
435	IN CHAR8 *HostName
436	);
437
438	/**
439	Sets a TLS/SSL session ID to be used during TLS/SSL connect.
440
441	This function sets a session ID to be used when the TLS/SSL connection is
442	to be established.
443
444	@param[in] Tls Pointer to the TLS object.
445	@param[in] SessionId Session ID data used for session resumption.
446	@param[in] SessionIdLen Length of Session ID in bytes.
447
448	@retval EFI_SUCCESS Session ID was set successfully.
449	@retval EFI_INVALID_PARAMETER The parameter is invalid.
450	@retval EFI_UNSUPPORTED No available session for ID setting.
451
452	**/
453	EFI_STATUS
454	EFIAPI
455	TlsSetSessionId (
456	IN VOID *Tls,
457	IN UINT8 *SessionId,
458	IN UINT16 SessionIdLen
459	);
460
461	/**
462	Adds the CA to the cert store when requesting Server or Client authentication.
463
464	This function adds the CA certificate to the list of CAs when requesting
465	Server or Client authentication for the chosen TLS connection.
466
467	@param[in] Tls Pointer to the TLS object.
468	@param[in] Data Pointer to the data buffer of a DER-encoded binary
469	X.509 certificate or PEM-encoded X.509 certificate.
470	@param[in] DataSize The size of data buffer in bytes.
471
472	@retval EFI_SUCCESS The operation succeeded.
473	@retval EFI_INVALID_PARAMETER The parameter is invalid.
474	@retval EFI_OUT_OF_RESOURCES Required resources could not be allocated.
475	@retval EFI_ABORTED Invalid X.509 certificate.
476
477	**/
478	EFI_STATUS
479	EFIAPI
480	TlsSetCaCertificate (
481	IN VOID *Tls,
482	IN VOID *Data,
483	IN UINTN DataSize
484	);
485
486	/**
487	Loads the local public certificate into the specified TLS object.
488
489	This function loads the X.509 certificate into the specified TLS object
490	for TLS negotiation.
491
492	@param[in] Tls Pointer to the TLS object.
493	@param[in] Data Pointer to the data buffer of a DER-encoded binary
494	X.509 certificate or PEM-encoded X.509 certificate.
495	@param[in] DataSize The size of data buffer in bytes.
496
497	@retval EFI_SUCCESS The operation succeeded.
498	@retval EFI_INVALID_PARAMETER The parameter is invalid.
499	@retval EFI_OUT_OF_RESOURCES Required resources could not be allocated.
500	@retval EFI_ABORTED Invalid X.509 certificate.
501
502	**/
503	EFI_STATUS
504	EFIAPI
505	TlsSetHostPublicCert (
506	IN VOID *Tls,
507	IN VOID *Data,
508	IN UINTN DataSize
509	);
510
511	/**
512	Adds the local private key to the specified TLS object.
513
514	This function adds the local private key (DER-encoded or PEM-encoded or PKCS#8 private
515	key) into the specified TLS object for TLS negotiation.
516
517	@param[in] Tls Pointer to the TLS object.
518	@param[in] Data Pointer to the data buffer of a DER-encoded or PEM-encoded
519	or PKCS#8 private key.
520	@param[in] DataSize The size of data buffer in bytes.
521	@param[in] Password Pointer to NULL-terminated private key password, set it to NULL
522	if private key not encrypted.
523
524	@retval EFI_SUCCESS The operation succeeded.
525	@retval EFI_UNSUPPORTED This function is not supported.
526	@retval EFI_ABORTED Invalid private key data.
527
528	**/
529	EFI_STATUS
530	EFIAPI
531	TlsSetHostPrivateKeyEx (
532	IN VOID *Tls,
533	IN VOID *Data,
534	IN UINTN DataSize,
535	IN VOID *Password OPTIONAL
536	);
537
538	/**
539	Adds the local private key to the specified TLS object.
540
541	This function adds the local private key (DER-encoded or PEM-encoded or PKCS#8 private
542	key) into the specified TLS object for TLS negotiation.
543
544	@param[in] Tls Pointer to the TLS object.
545	@param[in] Data Pointer to the data buffer of a DER-encoded or PEM-encoded
546	or PKCS#8 private key.
547	@param[in] DataSize The size of data buffer in bytes.
548
549	@retval EFI_SUCCESS The operation succeeded.
550	@retval EFI_UNSUPPORTED This function is not supported.
551	@retval EFI_ABORTED Invalid private key data.
552
553	**/
554	EFI_STATUS
555	EFIAPI
556	TlsSetHostPrivateKey (
557	IN VOID *Tls,
558	IN VOID *Data,
559	IN UINTN DataSize
560	);
561
562	/**
563	Adds the CA-supplied certificate revocation list for certificate validation.
564
565	This function adds the CA-supplied certificate revocation list data for
566	certificate validity checking.
567
568	@param[in] Data Pointer to the data buffer of a DER-encoded CRL data.
569	@param[in] DataSize The size of data buffer in bytes.
570
571	@retval EFI_SUCCESS The operation succeeded.
572	@retval EFI_UNSUPPORTED This function is not supported.
573	@retval EFI_ABORTED Invalid CRL data.
574
575	**/
576	EFI_STATUS
577	EFIAPI
578	TlsSetCertRevocationList (
579	IN VOID *Data,
580	IN UINTN DataSize
581	);
582
583	/**
584	Set the signature algorithm list to used by the TLS object.
585
586	This function sets the signature algorithms for use by a specified TLS object.
587
588	@param[in] Tls Pointer to a TLS object.
589	@param[in] Data Array of UINT8 of signature algorithms. The array consists of
590	pairs of the hash algorithm and the signature algorithm as defined
591	in RFC 5246
592	@param[in] DataSize The length the SignatureAlgoList. Must be divisible by 2.
593
594	@retval EFI_SUCCESS The signature algorithm list was set successfully.
595	@retval EFI_INVALID_PARAMETER The parameters are invalid.
596	@retval EFI_UNSUPPORTED No supported TLS signature algorithm was found in SignatureAlgoList
597	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.
598
599	**/
600	EFI_STATUS
601	EFIAPI
602	TlsSetSignatureAlgoList (
603	IN VOID *Tls,
604	IN UINT8 *Data,
605	IN UINTN DataSize
606	);
607
608	/**
609	Set the EC curve to be used for TLS flows
610
611	This function sets the EC curve to be used for TLS flows.
612
613	@param[in] Tls Pointer to a TLS object.
614	@param[in] Data An EC named curve as defined in section 5.1.1 of RFC 4492.
615	@param[in] DataSize Size of Data, it should be sizeof (UINT32)
616
617	@retval EFI_SUCCESS The EC curve was set successfully.
618	@retval EFI_INVALID_PARAMETER The parameters are invalid.
619	@retval EFI_UNSUPPORTED The requested TLS EC curve is not supported
620
621	**/
622	EFI_STATUS
623	EFIAPI
624	TlsSetEcCurve (
625	IN VOID *Tls,
626	IN UINT8 *Data,
627	IN UINTN DataSize
628	);
629
630	/**
631	Gets the protocol version used by the specified TLS connection.
632
633	This function returns the protocol version used by the specified TLS
634	connection.
635
636	If Tls is NULL, then ASSERT().
637
638	@param[in] Tls Pointer to the TLS object.
639
640	@return The protocol version of the specified TLS connection.
641
642	**/
643	UINT16
644	EFIAPI
645	TlsGetVersion (
646	IN VOID *Tls
647	);
648
649	/**
650	Gets the connection end of the specified TLS connection.
651
652	This function returns the connection end (as client or as server) used by
653	the specified TLS connection.
654
655	If Tls is NULL, then ASSERT().
656
657	@param[in] Tls Pointer to the TLS object.
658
659	@return The connection end used by the specified TLS connection.
660
661	**/
662	UINT8
663	EFIAPI
664	TlsGetConnectionEnd (
665	IN VOID *Tls
666	);
667
668	/**
669	Gets the cipher suite used by the specified TLS connection.
670
671	This function returns current cipher suite used by the specified
672	TLS connection.
673
674	@param[in] Tls Pointer to the TLS object.
675	@param[in,out] CipherId The cipher suite used by the TLS object.
676
677	@retval EFI_SUCCESS The cipher suite was returned successfully.
678	@retval EFI_INVALID_PARAMETER The parameter is invalid.
679	@retval EFI_UNSUPPORTED Unsupported cipher suite.
680
681	**/
682	EFI_STATUS
683	EFIAPI
684	TlsGetCurrentCipher (
685	IN VOID *Tls,
686	IN OUT UINT16 *CipherId
687	);
688
689	/**
690	Gets the compression methods used by the specified TLS connection.
691
692	This function returns current integrated compression methods used by
693	the specified TLS connection.
694
695	@param[in] Tls Pointer to the TLS object.
696	@param[in,out] CompressionId The current compression method used by
697	the TLS object.
698
699	@retval EFI_SUCCESS The compression method was returned successfully.
700	@retval EFI_INVALID_PARAMETER The parameter is invalid.
701	@retval EFI_ABORTED Invalid Compression method.
702	@retval EFI_UNSUPPORTED This function is not supported.
703
704	**/
705	EFI_STATUS
706	EFIAPI
707	TlsGetCurrentCompressionId (
708	IN VOID *Tls,
709	IN OUT UINT8 *CompressionId
710	);
711
712	/**
713	Gets the verification mode currently set in the TLS connection.
714
715	This function returns the peer verification mode currently set in the
716	specified TLS connection.
717
718	If Tls is NULL, then ASSERT().
719
720	@param[in] Tls Pointer to the TLS object.
721
722	@return The verification mode set in the specified TLS connection.
723
724	**/
725	UINT32
726	EFIAPI
727	TlsGetVerify (
728	IN VOID *Tls
729	);
730
731	/**
732	Gets the session ID used by the specified TLS connection.
733
734	This function returns the TLS/SSL session ID currently used by the
735	specified TLS connection.
736
737	@param[in] Tls Pointer to the TLS object.
738	@param[in,out] SessionId Buffer to contain the returned session ID.
739	@param[in,out] SessionIdLen The length of Session ID in bytes.
740
741	@retval EFI_SUCCESS The Session ID was returned successfully.
742	@retval EFI_INVALID_PARAMETER The parameter is invalid.
743	@retval EFI_UNSUPPORTED Invalid TLS/SSL session.
744
745	**/
746	EFI_STATUS
747	EFIAPI
748	TlsGetSessionId (
749	IN VOID *Tls,
750	IN OUT UINT8 *SessionId,
751	IN OUT UINT16 *SessionIdLen
752	);
753
754	/**
755	Gets the client random data used in the specified TLS connection.
756
757	This function returns the TLS/SSL client random data currently used in
758	the specified TLS connection.
759
760	@param[in] Tls Pointer to the TLS object.
761	@param[in,out] ClientRandom Buffer to contain the returned client
762	random data (32 bytes).
763
764	**/
765	VOID
766	EFIAPI
767	TlsGetClientRandom (
768	IN VOID *Tls,
769	IN OUT UINT8 *ClientRandom
770	);
771
772	/**
773	Gets the server random data used in the specified TLS connection.
774
775	This function returns the TLS/SSL server random data currently used in
776	the specified TLS connection.
777
778	@param[in] Tls Pointer to the TLS object.
779	@param[in,out] ServerRandom Buffer to contain the returned server
780	random data (32 bytes).
781
782	**/
783	VOID
784	EFIAPI
785	TlsGetServerRandom (
786	IN VOID *Tls,
787	IN OUT UINT8 *ServerRandom
788	);
789
790	/**
791	Gets the master key data used in the specified TLS connection.
792
793	This function returns the TLS/SSL master key material currently used in
794	the specified TLS connection.
795
796	@param[in] Tls Pointer to the TLS object.
797	@param[in,out] KeyMaterial Buffer to contain the returned key material.
798
799	@retval EFI_SUCCESS Key material was returned successfully.
800	@retval EFI_INVALID_PARAMETER The parameter is invalid.
801	@retval EFI_UNSUPPORTED Invalid TLS/SSL session.
802
803	**/
804	EFI_STATUS
805	EFIAPI
806	TlsGetKeyMaterial (
807	IN VOID *Tls,
808	IN OUT UINT8 *KeyMaterial
809	);
810
811	/**
812	Gets the CA Certificate from the cert store.
813
814	This function returns the CA certificate for the chosen
815	TLS connection.
816
817	@param[in] Tls Pointer to the TLS object.
818	@param[out] Data Pointer to the data buffer to receive the CA
819	certificate data sent to the client.
820	@param[in,out] DataSize The size of data buffer in bytes.
821
822	@retval EFI_SUCCESS The operation succeeded.
823	@retval EFI_UNSUPPORTED This function is not supported.
824	@retval EFI_BUFFER_TOO_SMALL The Data is too small to hold the data.
825
826	**/
827	EFI_STATUS
828	EFIAPI
829	TlsGetCaCertificate (
830	IN VOID *Tls,
831	OUT VOID *Data,
832	IN OUT UINTN *DataSize
833	);
834
835	/**
836	Gets the local public Certificate set in the specified TLS object.
837
838	This function returns the local public certificate which was currently set
839	in the specified TLS object.
840
841	@param[in] Tls Pointer to the TLS object.
842	@param[out] Data Pointer to the data buffer to receive the local
843	public certificate.
844	@param[in,out] DataSize The size of data buffer in bytes.
845
846	@retval EFI_SUCCESS The operation succeeded.
847	@retval EFI_INVALID_PARAMETER The parameter is invalid.
848	@retval EFI_NOT_FOUND The certificate is not found.
849	@retval EFI_BUFFER_TOO_SMALL The Data is too small to hold the data.
850
851	**/
852	EFI_STATUS
853	EFIAPI
854	TlsGetHostPublicCert (
855	IN VOID *Tls,
856	OUT VOID *Data,
857	IN OUT UINTN *DataSize
858	);
859
860	/**
861	Gets the local private key set in the specified TLS object.
862
863	This function returns the local private key data which was currently set
864	in the specified TLS object.
865
866	@param[in] Tls Pointer to the TLS object.
867	@param[out] Data Pointer to the data buffer to receive the local
868	private key data.
869	@param[in,out] DataSize The size of data buffer in bytes.
870
871	@retval EFI_SUCCESS The operation succeeded.
872	@retval EFI_UNSUPPORTED This function is not supported.
873	@retval EFI_BUFFER_TOO_SMALL The Data is too small to hold the data.
874
875	**/
876	EFI_STATUS
877	EFIAPI
878	TlsGetHostPrivateKey (
879	IN VOID *Tls,
880	OUT VOID *Data,
881	IN OUT UINTN *DataSize
882	);
883
884	/**
885	Gets the CA-supplied certificate revocation list data set in the specified
886	TLS object.
887
888	This function returns the CA-supplied certificate revocation list data which
889	was currently set in the specified TLS object.
890
891	@param[out] Data Pointer to the data buffer to receive the CRL data.
892	@param[in,out] DataSize The size of data buffer in bytes.
893
894	@retval EFI_SUCCESS The operation succeeded.
895	@retval EFI_UNSUPPORTED This function is not supported.
896	@retval EFI_BUFFER_TOO_SMALL The Data is too small to hold the data.
897
898	**/
899	EFI_STATUS
900	EFIAPI
901	TlsGetCertRevocationList (
902	OUT VOID *Data,
903	IN OUT UINTN *DataSize
904	);
905
906	/**
907	Derive keying material from a TLS connection.
908
909	This function exports keying material using the mechanism described in RFC
910	5705.
911
912	@param[in] Tls Pointer to the TLS object
913	@param[in] Label Description of the key for the PRF function
914	@param[in] Context Optional context
915	@param[in] ContextLen The length of the context value in bytes
916	@param[out] KeyBuffer Buffer to hold the output of the TLS-PRF
917	@param[in] KeyBufferLen The length of the KeyBuffer
918
919	@retval EFI_SUCCESS The operation succeeded.
920	@retval EFI_INVALID_PARAMETER The TLS object is invalid.
921	@retval EFI_PROTOCOL_ERROR Some other error occurred.
922
923	**/
924	EFI_STATUS
925	EFIAPI
926	TlsGetExportKey (
927	IN VOID *Tls,
928	IN CONST VOID *Label,
929	IN CONST VOID *Context,
930	IN UINTN ContextLen,
931	OUT VOID *KeyBuffer,
932	IN UINTN KeyBufferLen
933	);
934
935	#endif // __TLS_LIB_H__

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/CryptoPkg/Include/Library/TlsLib.h@ 105681

Download in other formats: