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