1 /** @file 2 EFI Storage Security Command Protocol as defined in UEFI 2.3.1 specification. 3 This protocol is used to abstract mass storage devices to allow code running in 4 the EFI boot services environment to send security protocol commands to mass 5 storage devices without specific knowledge of the type of device or controller 6 that manages the device. 7 8 Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR> 9 SPDX-License-Identifier: BSD-2-Clause-Patent 10 11 **/ 12 13 #ifndef __STORAGE_SECURITY_COMMAND_H__ 14 #define __STORAGE_SECURITY_COMMAND_H__ 15 16 #define EFI_STORAGE_SECURITY_COMMAND_PROTOCOL_GUID \ 17 { \ 18 0xC88B0B6D, 0x0DFC, 0x49A7, {0x9C, 0xB4, 0x49, 0x07, 0x4B, 0x4C, 0x3A, 0x78 } \ 19 } 20 21 typedef struct _EFI_STORAGE_SECURITY_COMMAND_PROTOCOL EFI_STORAGE_SECURITY_COMMAND_PROTOCOL; 22 23 /** 24 Send a security protocol command to a device that receives data and/or the result 25 of one or more commands sent by SendData. 26 27 The ReceiveData function sends a security protocol command to the given MediaId. 28 The security protocol command sent is defined by SecurityProtocolId and contains 29 the security protocol specific data SecurityProtocolSpecificData. The function 30 returns the data from the security protocol command in PayloadBuffer. 31 32 For devices supporting the SCSI command set, the security protocol command is sent 33 using the SECURITY PROTOCOL IN command defined in SPC-4. 34 35 For devices supporting the ATA command set, the security protocol command is sent 36 using one of the TRUSTED RECEIVE commands defined in ATA8-ACS if PayloadBufferSize 37 is non-zero. 38 39 If the PayloadBufferSize is zero, the security protocol command is sent using the 40 Trusted Non-Data command defined in ATA8-ACS. 41 42 If PayloadBufferSize is too small to store the available data from the security 43 protocol command, the function shall copy PayloadBufferSize bytes into the 44 PayloadBuffer and return EFI_WARN_BUFFER_TOO_SMALL. 45 46 If PayloadBuffer or PayloadTransferSize is NULL and PayloadBufferSize is non-zero, 47 the function shall return EFI_INVALID_PARAMETER. 48 49 If the given MediaId does not support security protocol commands, the function shall 50 return EFI_UNSUPPORTED. If there is no media in the device, the function returns 51 EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, 52 the function returns EFI_MEDIA_CHANGED. 53 54 If the security protocol fails to complete within the Timeout period, the function 55 shall return EFI_TIMEOUT. 56 57 If the security protocol command completes without an error, the function shall 58 return EFI_SUCCESS. If the security protocol command completes with an error, the 59 function shall return EFI_DEVICE_ERROR. 60 61 @param This Indicates a pointer to the calling context. 62 @param MediaId ID of the medium to receive data from. 63 @param Timeout The timeout, in 100ns units, to use for the execution 64 of the security protocol command. A Timeout value of 0 65 means that this function will wait indefinitely for the 66 security protocol command to execute. If Timeout is greater 67 than zero, then this function will return EFI_TIMEOUT if the 68 time required to execute the receive data command is greater than Timeout. 69 @param SecurityProtocolId The value of the "Security Protocol" parameter of 70 the security protocol command to be sent. 71 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter 72 of the security protocol command to be sent. 73 @param PayloadBufferSize Size in bytes of the payload data buffer. 74 @param PayloadBuffer A pointer to a destination buffer to store the security 75 protocol command specific payload data for the security 76 protocol command. The caller is responsible for having 77 either implicit or explicit ownership of the buffer. 78 @param PayloadTransferSize A pointer to a buffer to store the size in bytes of the 79 data written to the payload data buffer. 80 81 @retval EFI_SUCCESS The security protocol command completed successfully. 82 @retval EFI_WARN_BUFFER_TOO_SMALL The PayloadBufferSize was too small to store the available 83 data from the device. The PayloadBuffer contains the truncated data. 84 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands. 85 @retval EFI_DEVICE_ERROR The security protocol command completed with an error. 86 @retval EFI_NO_MEDIA There is no media in the device. 87 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 88 @retval EFI_INVALID_PARAMETER The PayloadBuffer or PayloadTransferSize is NULL and 89 PayloadBufferSize is non-zero. 90 @retval EFI_TIMEOUT A timeout occurred while waiting for the security 91 protocol command to execute. 92 93 **/ 94 typedef 95 EFI_STATUS 96 (EFIAPI *EFI_STORAGE_SECURITY_RECEIVE_DATA)( 97 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This, 98 IN UINT32 MediaId, 99 IN UINT64 Timeout, 100 IN UINT8 SecurityProtocolId, 101 IN UINT16 SecurityProtocolSpecificData, 102 IN UINTN PayloadBufferSize, 103 OUT VOID *PayloadBuffer, 104 OUT UINTN *PayloadTransferSize 105 ); 106 107 /** 108 Send a security protocol command to a device. 109 110 The SendData function sends a security protocol command containing the payload 111 PayloadBuffer to the given MediaId. The security protocol command sent is 112 defined by SecurityProtocolId and contains the security protocol specific data 113 SecurityProtocolSpecificData. If the underlying protocol command requires a 114 specific padding for the command payload, the SendData function shall add padding 115 bytes to the command payload to satisfy the padding requirements. 116 117 For devices supporting the SCSI command set, the security protocol command is sent 118 using the SECURITY PROTOCOL OUT command defined in SPC-4. 119 120 For devices supporting the ATA command set, the security protocol command is sent 121 using one of the TRUSTED SEND commands defined in ATA8-ACS if PayloadBufferSize 122 is non-zero. If the PayloadBufferSize is zero, the security protocol command is 123 sent using the Trusted Non-Data command defined in ATA8-ACS. 124 125 If PayloadBuffer is NULL and PayloadBufferSize is non-zero, the function shall 126 return EFI_INVALID_PARAMETER. 127 128 If the given MediaId does not support security protocol commands, the function 129 shall return EFI_UNSUPPORTED. If there is no media in the device, the function 130 returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the 131 device, the function returns EFI_MEDIA_CHANGED. 132 133 If the security protocol fails to complete within the Timeout period, the function 134 shall return EFI_TIMEOUT. 135 136 If the security protocol command completes without an error, the function shall return 137 EFI_SUCCESS. If the security protocol command completes with an error, the function 138 shall return EFI_DEVICE_ERROR. 139 140 @param This Indicates a pointer to the calling context. 141 @param MediaId ID of the medium to receive data from. 142 @param Timeout The timeout, in 100ns units, to use for the execution 143 of the security protocol command. A Timeout value of 0 144 means that this function will wait indefinitely for the 145 security protocol command to execute. If Timeout is greater 146 than zero, then this function will return EFI_TIMEOUT if the 147 time required to execute the receive data command is greater than Timeout. 148 @param SecurityProtocolId The value of the "Security Protocol" parameter of 149 the security protocol command to be sent. 150 @param SecurityProtocolSpecificData The value of the "Security Protocol Specific" parameter 151 of the security protocol command to be sent. 152 @param PayloadBufferSize Size in bytes of the payload data buffer. 153 @param PayloadBuffer A pointer to a destination buffer to store the security 154 protocol command specific payload data for the security 155 protocol command. 156 157 @retval EFI_SUCCESS The security protocol command completed successfully. 158 @retval EFI_UNSUPPORTED The given MediaId does not support security protocol commands. 159 @retval EFI_DEVICE_ERROR The security protocol command completed with an error. 160 @retval EFI_NO_MEDIA There is no media in the device. 161 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media. 162 @retval EFI_INVALID_PARAMETER The PayloadBuffer is NULL and PayloadBufferSize is non-zero. 163 @retval EFI_TIMEOUT A timeout occurred while waiting for the security 164 protocol command to execute. 165 166 **/ 167 typedef 168 EFI_STATUS 169 (EFIAPI *EFI_STORAGE_SECURITY_SEND_DATA)( 170 IN EFI_STORAGE_SECURITY_COMMAND_PROTOCOL *This, 171 IN UINT32 MediaId, 172 IN UINT64 Timeout, 173 IN UINT8 SecurityProtocolId, 174 IN UINT16 SecurityProtocolSpecificData, 175 IN UINTN PayloadBufferSize, 176 IN VOID *PayloadBuffer 177 ); 178 179 /// 180 /// The EFI_STORAGE_SECURITY_COMMAND_PROTOCOL is used to send security protocol 181 /// commands to a mass storage device. Two types of security protocol commands 182 /// are supported. SendData sends a command with data to a device. ReceiveData 183 /// sends a command that receives data and/or the result of one or more commands 184 /// sent by SendData. 185 /// 186 /// The security protocol command formats supported shall be based on the definition 187 /// of the SECURITY PROTOCOL IN and SECURITY PROTOCOL OUT commands defined in SPC-4. 188 /// If the device uses the SCSI command set, no translation is needed in the firmware 189 /// and the firmware can package the parameters into a SECURITY PROTOCOL IN or SECURITY 190 /// PROTOCOL OUT command and send the command to the device. If the device uses a 191 /// non-SCSI command set, the firmware shall map the command and data payload to the 192 /// corresponding command and payload format defined in the non-SCSI command set 193 /// (for example, TRUSTED RECEIVE and TRUSTED SEND in ATA8-ACS). 194 /// 195 /// The firmware shall automatically add an EFI_STORAGE_SECURITY_COMMAND_PROTOCOL 196 /// for any storage devices detected during system boot that support SPC-4, ATA8-ACS 197 /// or their successors. 198 /// 199 struct _EFI_STORAGE_SECURITY_COMMAND_PROTOCOL { 200 EFI_STORAGE_SECURITY_RECEIVE_DATA ReceiveData; 201 EFI_STORAGE_SECURITY_SEND_DATA SendData; 202 }; 203 204 extern EFI_GUID gEfiStorageSecurityCommandProtocolGuid; 205 206 #endif 207