[efi] Add storage security command protocol header and GUID definition

Signed-off-by: Michael Brown <mcb30@ipxe.org>

diff --git a/src/include/ipxe/efi/Protocol/StorageSecurityCommand.h b/src/include/ipxe/efi/Protocol/StorageSecurityCommand.h
new file mode 100644 (file)
index 0000000..9e53de7
--- /dev/null
+++ b/src/include/ipxe/efi/Protocol/StorageSecurityCommand.h
@@ -0,0 +1,212 @@
+/** @file
+  EFI Storage Security Command Protocol as defined in UEFI 2.3.1 specification.
+  This protocol is used to abstract mass storage devices to allow code running in
+  the EFI boot services environment to send security protocol commands to mass
+  storage devices without specific knowledge of the type of device or controller
+  that manages the device.
+
+  Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef __STORAGE_SECURITY_COMMAND_H__
+#define __STORAGE_SECURITY_COMMAND_H__
+
+FILE_LICENCE ( BSD2_PATENT );
+
+#define EFI_STORAGE_SECURITY_COMMAND_PROTOCOL_GUID \
+  { \
+    0xC88B0B6D, 0x0DFC, 0x49A7, {0x9C, 0xB4, 0x49, 0x07, 0x4B, 0x4C, 0x3A, 0x78 } \
+  }
+
+typedef struct _EFI_STORAGE_SECURITY_COMMAND_PROTOCOL EFI_STORAGE_SECURITY_COMMAND_PROTOCOL;
+
+/**
+  Send a security protocol command to a device that receives data and/or the result
+  of one or more commands sent by SendData.
+
+  The ReceiveData function sends a security protocol command to the given MediaId.
+  The security protocol command sent is defined by SecurityProtocolId and contains
+  the security protocol specific data SecurityProtocolSpecificData. The function
+  returns the data from the security protocol command in PayloadBuffer.
+
+  For devices supporting the SCSI command set, the security protocol command is sent
+  using the SECURITY PROTOCOL IN command defined in SPC-4.
+
+  For devices supporting the ATA command set, the security protocol command is sent
+  using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize
+  is non-zero.
+
+  If the PayloadBufferSize is zero, the security protocol command is sent using the
+  Trusted Non-Data command defined in ATA8-ACS.
+
+  If PayloadBufferSize is too small to store the available data from the security
+  protocol command, the function shall copy PayloadBufferSize bytes into the
+  PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL.
+
+  If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero,
+  the function shall return EFI_INVALID_PARAMETER.
+
+  If the given MediaId does not support security protocol commands, the function shall
+  return EFI_UNSUPPORTED. If there is no media in the device, the function returns
+  EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device,
+  the function returns EFI_MEDIA_CHANGED.
+
+  If the security protocol fails to complete within the Timeout period, the function
+  shall return EFI_TIMEOUT.
+
+  If the security protocol command completes without an error, the function shall
+  return EFI_SUCCESS. If the security protocol command completes with an error, the
+  function shall return EFI_DEVICE_ERROR.
+
+  @param  This                         Indicates a pointer to the calling context.
+  @param  MediaId                      ID of the medium to receive data from. If there is no
+                                       block IO protocol supported by the physical device, the
+                                       value of MediaId is undefined.
+  @param  Timeout                      The timeout, in 100ns units, to use for the execution
+                                       of the security protocol command. A Timeout value of 0
+                                       means that this function will wait indefinitely for the
+                                       security protocol command to execute. If Timeout is greater
+                                       than zero, then this function will return EFI_TIMEOUT if the
+                                       time required to execute the receive data command is greater than Timeout.
+  @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
+                                       the security protocol command to be sent.
+  @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
+                                       of the security protocol command to be sent.
+  @param  PayloadBufferSize            Size in bytes of the payload data buffer.
+  @param  PayloadBuffer                A pointer to a destination buffer to store the security
+                                       protocol command specific payload data for the security
+                                       protocol command. The caller is responsible for having
+                                       either implicit or explicit ownership of the buffer.
+  @param  PayloadTransferSize          A pointer to a buffer to store the size in bytes of the
+                                       data written to the payload data buffer.
+
+  @retval EFI_SUCCESS                  The security protocol command completed successfully.
+  @retval EFI_WARN_BUFFER_TOO_SMALL    The PayloadBufferSize was too small to store the available
+                                       data from the device. The PayloadBuffer contains the truncated data.
+  @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
+  @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
+  @retval EFI_NO_MEDIA                 There is no media in the device.
+  @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
+  @retval EFI_INVALID_PARAMETER        The PayloadBuffer or PayloadTransferSize is NULL and
+                                       PayloadBufferSize is non-zero.
+  @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
+                                       protocol command to execute.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_STORAGE_SECURITY_RECEIVE_DATA)(
+  IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
+  IN UINT32                                   MediaId,
+  IN UINT64                                   Timeout,
+  IN UINT8                                    SecurityProtocolId,
+  IN UINT16                                   SecurityProtocolSpecificData,
+  IN UINTN                                    PayloadBufferSize,
+  OUT VOID                                    *PayloadBuffer,
+  OUT UINTN                                   *PayloadTransferSize
+  );
+
+/**
+  Send a security protocol command to a device.
+
+  The SendData function sends a security protocol command containing the payload
+  PayloadBuffer to the given MediaId. The security protocol command sent is
+  defined by SecurityProtocolId and contains the security protocol specific data
+  SecurityProtocolSpecificData. If the underlying protocol command requires a
+  specific padding for the command payload, the SendData function shall add padding
+  bytes to the command payload to satisfy the padding requirements.
+
+  For devices supporting the SCSI command set, the security protocol command is sent
+  using the SECURITY PROTOCOL OUT command defined in SPC-4.
+
+  For devices supporting the ATA command set, the security protocol command is sent
+  using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize
+  is non-zero. If the PayloadBufferSize is zero, the security protocol command is
+  sent using the Trusted Non-Data command defined in ATA8-ACS.
+
+  If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall
+  return EFI_INVALID_PARAMETER.
+
+  If the given MediaId does not support security protocol commands, the function
+  shall return EFI_UNSUPPORTED. If there is no media in the device, the function
+  returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the
+  device, the function returns EFI_MEDIA_CHANGED.
+
+  If the security protocol fails to complete within the Timeout period, the function
+  shall return EFI_TIMEOUT.
+
+  If the security protocol command completes without an error, the function shall return
+  EFI_SUCCESS. If the security protocol command completes with an error, the function
+  shall return EFI_DEVICE_ERROR.
+
+  @param  This                         Indicates a pointer to the calling context.
+  @param  MediaId                      ID of the medium to receive data from. If there is no
+                                       block IO protocol supported by the physical device, the
+                                       value of MediaId is undefined.
+  @param  Timeout                      The timeout, in 100ns units, to use for the execution
+                                       of the security protocol command. A Timeout value of 0
+                                       means that this function will wait indefinitely for the
+                                       security protocol command to execute. If Timeout is greater
+                                       than zero, then this function will return EFI_TIMEOUT if the
+                                       time required to execute the receive data command is greater than Timeout.
+  @param  SecurityProtocolId           The value of the "Security Protocol" parameter of
+                                       the security protocol command to be sent.
+  @param  SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter
+                                       of the security protocol command to be sent.
+  @param  PayloadBufferSize            Size in bytes of the payload data buffer.
+  @param  PayloadBuffer                A pointer to a destination buffer to store the security
+                                       protocol command specific payload data for the security
+                                       protocol command.
+
+  @retval EFI_SUCCESS                  The security protocol command completed successfully.
+  @retval EFI_UNSUPPORTED              The given MediaId does not support security protocol commands.
+  @retval EFI_DEVICE_ERROR             The security protocol command completed with an error.
+  @retval EFI_NO_MEDIA                 There is no media in the device.
+  @retval EFI_MEDIA_CHANGED            The MediaId is not for the current media.
+  @retval EFI_INVALID_PARAMETER        The PayloadBuffer is NULL and PayloadBufferSize is non-zero.
+  @retval EFI_TIMEOUT                  A timeout occurred while waiting for the security
+                                       protocol command to execute.
+
+**/
+typedef
+EFI_STATUS
+(EFIAPI *EFI_STORAGE_SECURITY_SEND_DATA)(
+  IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL    *This,
+  IN UINT32                                   MediaId,
+  IN UINT64                                   Timeout,
+  IN UINT8                                    SecurityProtocolId,
+  IN UINT16                                   SecurityProtocolSpecificData,
+  IN UINTN                                    PayloadBufferSize,
+  IN VOID                                     *PayloadBuffer
+  );
+
+///
+/// The EFI_STORAGE_SECURITY_COMMAND_PROTOCOL is used to send security protocol
+/// commands to a mass storage device. Two types of security protocol commands
+/// are supported. SendData sends a command with data to a device. ReceiveData
+/// sends a command that receives data and/or the result of one or more commands
+/// sent by SendData.
+///
+/// The security protocol command formats supported shall be based on the definition
+/// of the SECURITY PROTOCOL IN and SECURITY PROTOCOL OUT commands defined in SPC-4.
+/// If the device uses the SCSI command set, no translation is needed in the firmware
+/// and the firmware can package the parameters into a SECURITY PROTOCOL IN or SECURITY
+/// PROTOCOL OUT command and send the command to the device. If the device uses a
+/// non-SCSI command set, the firmware shall map the command and data payload to the
+/// corresponding command and payload format defined in the non-SCSI command set
+/// (for example, TRUSTED RECEIVE and TRUSTED SEND in ATA8-ACS).
+///
+/// The firmware shall automatically add an EFI_STORAGE_SECURITY_COMMAND_PROTOCOL
+/// for any storage devices detected during system boot that support SPC-4, ATA8-ACS
+/// or their successors.
+///
+struct _EFI_STORAGE_SECURITY_COMMAND_PROTOCOL {
+  EFI_STORAGE_SECURITY_RECEIVE_DATA    ReceiveData;
+  EFI_STORAGE_SECURITY_SEND_DATA       SendData;
+};
+
+extern EFI_GUID  gEfiStorageSecurityCommandProtocolGuid;
+
+#endif

diff --git a/src/include/ipxe/efi/efi.h b/src/include/ipxe/efi/efi.h
index 9dd26bff00736908f2b14c4c7a50f2852e566044..30b10f5078b805e52508501601539617a5069c61 100644 (file)
--- a/src/include/ipxe/efi/efi.h
+++ b/src/include/ipxe/efi/efi.h
@@ -233,6 +233,7 @@ extern EFI_GUID efi_simple_pointer_protocol_guid;
 extern EFI_GUID efi_simple_text_input_protocol_guid;
 extern EFI_GUID efi_simple_text_input_ex_protocol_guid;
 extern EFI_GUID efi_simple_text_output_protocol_guid;
+extern EFI_GUID efi_storage_security_command_protocol_guid;
 extern EFI_GUID efi_supplicant_protocol_guid;
 extern EFI_GUID efi_tcg_protocol_guid;
 extern EFI_GUID efi_tcg2_protocol_guid;

diff --git a/src/interface/efi/efi_guid.c b/src/interface/efi/efi_guid.c
index 824db1b9a341fe3e2316fc5b7a82d8fb87980b00..8c8c06d7c04f7764219697b755dfd234484c799c 100644 (file)
--- a/src/interface/efi/efi_guid.c
+++ b/src/interface/efi/efi_guid.c
@@ -74,6 +74,7 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 #include <ipxe/efi/Protocol/SimpleTextIn.h>
 #include <ipxe/efi/Protocol/SimpleTextInEx.h>
 #include <ipxe/efi/Protocol/SimpleTextOut.h>
+#include <ipxe/efi/Protocol/StorageSecurityCommand.h>
 #include <ipxe/efi/Protocol/Supplicant.h>
 #include <ipxe/efi/Protocol/TcgService.h>
 #include <ipxe/efi/Protocol/Tcg2Protocol.h>
@@ -353,6 +354,10 @@ EFI_GUID efi_simple_text_input_ex_protocol_guid
 EFI_GUID efi_simple_text_output_protocol_guid
        = EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL_GUID;
 
+/** Storage security protocol GUID */
+EFI_GUID efi_storage_security_command_protocol_guid
+       = EFI_STORAGE_SECURITY_COMMAND_PROTOCOL_GUID;
+
 /** Supplicant protocol GUID */
 EFI_GUID efi_supplicant_protocol_guid
        = EFI_SUPPLICANT_PROTOCOL_GUID;
@@ -650,6 +655,8 @@ static struct efi_well_known_guid efi_well_known_guids[] = {
          "Smbios" },
        { &efi_smbios3_table_guid,
          "Smbios3" },
+       { &efi_storage_security_command_protocol_guid,
+         "StorageSecurityCommand" },
        { &efi_supplicant_protocol_guid,
          "Supplicant" },
        { &efi_tcg_protocol_guid,