American Megatrends, Inc.

OpalSecurity

Copyright

Release Notes

© American Megatrends, Inc.


Copyright

American Megatrends, Inc.
5555 Oakbrook Parkway
Suite 200
Norcross, GA 30093 (USA)

Copyright (c) 1999-2011 American Megatrends, Inc. All Rights Reserved.

This publication contains proprietary information, which is protected by copyright. No part of this publication may be reproduced, transcribed, stored in a retrieval system, translated into any language or computer language, or transmitted in any form whatsoever without the prior written consent of the publisher, American Megatrends, Inc.

American Megatrends, Inc. retains the right to update, change, modify this publication at any time, without notice.

For Additional Information

Call American Megatrends BIOS Sales Department at 1-800-828-9264 for additional information.

Limitations of Liability

In no event shall American Megatrends be held liable for any loss, expenses, or damages of any kind whatsoever, whether direct, indirect, incidental, or consequential, arising from the design or use of this product or the support materials provided with the product.

Limited Warranty

No warranties are made, either expressed or implied, with regard to the contents of this work, its merchantability, or fitness for a particular use. American Megatrends assumes no responsibility for errors and omissions or for the uses made of the material contained herein or reader decisions based on such use.

Trademark and Copyright Acknowledgments

All product names used in this publication are for identification purposes only and are trademarks of their respective Companies.


Release Notes - NDA Required

Component Information:
Component Title: Opal Security
Component Reference Name: Opal Security
Component Type: eModule
Release Date: 2011-12-28
Source Control Label: 4.6.5.2_OpalSecurity_002
Source Control Location: SS: $/Alaska/Source/Modules/OpalSecurity/OPALSECURITY

Driver Dependencies
Idebus(4.6.5.2) or AhciBus(4.6.3_AhciSrc_018)
Protocol Dependencies
N0NE
File Dependencies
N0NE

Non-Compiled BIN and LIB File(s) within this Component:
N0NE
Component Description:
Opal Security is a separate eModule in Aptio™ that provides protocol interface for OPAL Security Subsystem Class (SSC) drives. The Opal SSC is an implementation profile for Storage Devices built to:

  • Protect the confidentiality of stored user data against unauthorized access once it leaves the owner’s control(involving a power cycle and subsequent de-authentication)

  • Enable interoperability between multiple SD vendors.

Opal Security driver implements security protocol (EFI_STORAGE_SECURITY_COMMAND_PROTOCOL) defined by UEFI2.3 specification (Chapter12) for media access.
NOTE:
This Opal driver interface that only Send/Receives TRUSTED COMMAND complies with Opal_SSC_2.00_rev1.06
Control Flow:
The eModule will provide interface to install EFI_STORAGE_SECURITY_COMMAND_PROTOCOL if trusted commands supported by the drives. The Opal Security interface will be installed in AHCI and IDE bus driver while other security related protocols are installed.
Porting Needed:
No porting required as this driver only provides the interface for OPALSSC.
General Communication Model Example

Filename | Description
OpalSecurity.sdl | SDL file to configure the module.Token available to enable/disable the Opal Security.
OpalSecurity.mak | Make file to build OpalSecurity module
OpalSecurity.c | Entry point for the driver is implemented in this file. Implementation to install OpalSecurity interface and StorageSecurity protocol is done in this file
OpalSecurity.h | This file contains the Includes, Definitions, typedefs, Variable and External Declarations, Structure and function prototypes needed for the OpalSecurity driver.
OpalSecurity.cif | This file contains the list of files present in the Module
OpalSecurity.chm | This file contains the help information for the module.
IDEOpalSec.c | This file has the Opal Security protocol interface for IDE mode.
AHCIOpalSec.c | This file has the Opal Security protocol interface for AHCI mode.

BIOS Parameters:
Parameter Name | Type | Description
OpalSecurity_SUPPORT | Boolean | Main switch to enable OpalSecurity support in Project
TPer_LOCK_ON_RESET | Boolean | Issue eDrive Lock On Reset
AMI Build Tools:
Tools Label: 4.5.5_Tools_35, Dated: 2011-03-29
Visual eBios: RSS.5.70.0171, Dated: 2010-10-04
Compiler Tool(s):Microsoft Windows Driver Kit (WDK) Ver.7600.16385.1
New features added in this label:
None
General Bug Fixes:
  • EIP77142 : BUG FIX - Changed Little Endian format to Big Endian format while sending commands.
    IMPROVEMENT - Added support to Lock the Opal hdd if it's unlocked on Bios POST.
EIP addressed in this label:
  • EIP77142 : BUG FIX - Changed Little Endian format to Big Endian format while sending commands.
    IMPROVEMENT - Added support to Lock the Opal hdd if it's unlocked on Bios POST.
Files changed for EIP fixes:
  • Root\core\em\OpalSecurity\OpalSecurity.sdl(Eip#77142)
  • Root\core\em\OpalSecurity\OpalSecurity.c(Eip#77142)
  • Root\core\em\OpalSecurity\OpalSecurity.h(Eip#77142)
  • Root\core\em\OpalSecurity\IDEOpalSec.c(Eip#77142)
  • Root\core\em\OpalSecurity\AHCIOpalSec.c(Eip#77142)
Known issues and limitations in this label:
None
Remaining Issues:
None
Unit Testing:
OpalVal Efi Shell Application has been developed w.r.t EIP 53565 and verified with Opal and Non Opal Drives for Compliance.
Validation Test Report

Validation Test Report.
Release History:
Label 4.6.5.2_OpalSecurity_002:
  • [TAG] - EIP77142
    [Category] - BUG FIX & IMPROVEMENT
    [Description] - BUG FIX - Changed Little Endian format to Big Endian format while sending commands.
    IMPROVEMENT - Added support to Lock the Opal hdd if it's unlocked on Bios POST.
    [Files] - IdeOpalSec.c, AhciOpalSec.c, OpalSecurity.c, OpalSecurity.h, OpalSecurity.sdl

Label (INT)a_4.6.5.1_OpalSecurity_002:
  • [TAG] - EIP64040
    [Category] - Improvement
    [Description] - Opal Security - Changes requested for CodeReview by customer
    [Files] - IdeOpalSec.c, AhciOpalSec.c

  • [TAG] - EIP67653
    [Category] - Improvement
    [Description] - Source Control Location path for Opal Security module is incorrect in OpalSecurity.chm file
    [Files] - OpalSecuriy.chm

  • [TAG] - EIP62912
    [Category] - Improvement
    [Description] - Opal Security Definitions Should be Moved to PIDEBUS.h from StorageSecurityProtocol.h
    StorageSecurityProtocol.h included in OPAL security driver module will give build error when disabled without sdl token #if OpalSecurity_SUPPORT properly placed in Ahcibus and IdeBus drivers.
    But Bus driver should not depend on any tokens. For this reason need to move OPAL_SEC_INIT_PROTOCOL_GUID in Pidebus.h
    [Files] - IdeBus.c, Pidebus.h, OpalSecurity.cif, OpalSecurity.h, IdeOpalSec.c, AhciOpalSec.c

For this Module to work, following versions of the files need to be present for compatibility until Idebus and Ahci Modules are Labeled and Updated for Project.
  • PIDEBUS.h - Sourcesafe Version 22 or Later
  • Idebus.c - Sourcesafe Version 54 or Later
  • Ahcibus.c - Sourcesafe Version 40 or Later

StorageSecurityCommand.h is available from 4.6.5.1 label which is a part of UEFI Spec. Hence opal security driver is modified by removing the StorageSecurityProtocol module part that had StorageSecurityProtocol.h existed previous label.Projects that are updating from Label 001 to Label 002 should also make sure .veb file is removed of this StorageSecurityProtocol Module part entry to aviod build errors.

Sources below 4.6.4 should use previous label. Label 002 od Opal security Driver will support 4.6.5.1.

Label 4.6.4_Opal_Security_001: Initial Check in

For this Module to work, following versions of the files need to be present for compatibility until Idebus and Ahci Modules are Labeled and Updated for Project.
  • PIDEBUS.h - Sourcesafe Version 20 or Later
  • Idebus.c - Sourcesafe Version 50 or Later
  • Ahcibus.c - Sourcesafe Version 40 or Later

© American Megatrends Inc.


Release Notes - NDA Required

Validation Test Report for OpalSecurity Label (INT)b_4.6.5.2_OpalSecurity_002

Platform Information Form :

Board Information - Piketon
BIOS Information (Label, Path) - Labeled'(INT)4.6.5_DH55HC_21';SS: Alaska;$/Alaska/Projects/Intel/Piketon/DH55HC/DH55HC.veb';
Chipset Information (Type, Stepping) -
CPU Information (Type, Stepping) -
Memory Info (Manufacturer, Speed, Configuration) -
Graphics (Please specify which one in used) -
Chipset driver Version -
Graphics drive Version -

Opal Security

1) REF-32553: EFI Non-Opal HDD Detection ---- PASS
Status Update:

2) REF-32552: EFI Opal HDD Detection ---- PASS
Status Update:


Function by File Name

AMIBIOS Function Reference

By File Name

The following is a list of the .asm files.
For a list in alphabetical order, see In Alphabetical Order.

  • AHCIOpalSec.c
  • IDEOpalSec.c
  • OpalSecurity.c
  • OpalSecurity.h
  • OpalSecurity.mak
Built on 16:45:17 12/28/11


AHCIOpalSec.c

Description:
Opal Support

The following functions are used in the file: AHCIOpalSec.c.

Function | Description
AhciSendData | Send a security protocol command to a device.
ReceiveData | Send a security protocol command to a device that receives data and/or the result of one or more commands sent by SendData.


AhciSendData in the AHCIOpalSec.c

Function : AhciSendData

File: AHCIOpalSec.c
Description:
Send a security protocol command to a device.
Input:
This - Indicates a pointer to the calling context. Type
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL is defined in the
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL description.
MediaId - ID of the medium to send data to.
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.
SecurityProtocolId - Security protocol ID of the security protocol
          command to be sent.
SecurityProtocolSpecificData - Security protocol specific portion of
                    the security protocol command.
PayloadBufferSize    - Size in bytes of the payload data buffer.
PayloadBuffer - A pointer to a buffer containing the security protocol
     command specific payload data for the security protocol command.
Output:
EFI_SUCCESS         - The security protocol command completed successfully.
EFI_UNSUPPORTED     - The given MediaId does not support security protocol
            commands.
EFI_DEVICE_ERROR     - The security protocol command completed with an error.
EFI_INVALID_PARAMETER - The PayloadBuffer or PayloadTransferSize is
             NULL and PayloadBufferSize is non-zero.


ReceiveData in the AHCIOpalSec.c

Function : ReceiveData

File: AHCIOpalSec.c
Description:
Send a security protocol command to a device that receives
data and/or the result of one or more commands sent by
SendData.
Input:
This -Indicates a pointer to the calling context. Type
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL is defined in the
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL description.
MediaId - ID of the medium to receive data from.
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.
SecurityProtocolId - Security protocol ID of the security protocol
command to be sent.
SecurityProtocolSpecificData - Security protocol specific portion of
 the security protocol command.
PayloadBufferSize - Size in bytes of the payload data buffer.
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 either having implicit or explicit ownership of
the buffer.
PayloadTransferSize - A pointer to a buffer to store the size in bytes
of the data written to the payload data buffer.
Output:
EFI_SUCCESS - The security protocol command completed successfully.
EFI_UNSUPPORTED - The given MediaId does not support security
protocol commands.
EFI_DEVICE_ERROR - The security protocol command completed with an error.
EFI_INVALID_PARAMETER - The PayloadBuffer or PayloadTransferSize is
   NULL and PayloadBufferSize is non-zero.


IDEOpalSec.c

Description:
IDE Opal Security Support

The following functions are used in the file: IDEOpalSec.c.

Function | Description
IdeReceiveData | Send a security protocol command to a device that receives data and/or the result of one or more commands sent by SendData.
IdeSendData | Send a security protocol command to a device.


IdeReceiveData in the IDEOpalSec.c

Function : IdeReceiveData

File: IDEOpalSec.c
Description:
Send a security protocol command to a device that receives
data and/or the result of one or more commands sent by
SendData.
Input:
This -Indicates a pointer to the calling context. Type
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL is defined in the
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL description.
MediaId - ID of the medium to receive data from.
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.
SecurityProtocolId - Security protocol ID of the security protocol
command to be sent.
SecurityProtocolSpecificData - Security protocol specific portion of
the security protocol command.
PayloadBufferSize - Size in bytes of the payload data buffer.
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 either having implicit or
explicit ownership of the buffer.
PayloadTransferSize - A pointer to a buffer to store the size in bytes
of the data written to the payload data buffer.
Output:
EFI_SUCCESS - The security protocol command completed successfully.
EFI_UNSUPPORTED - The given MediaId does not support security
protocol commands.
EFI_DEVICE_ERROR - The security protocol command completed with an error.
EFI_INVALID_PARAMETER - The PayloadBuffer or PayloadTransferSize is
NULL and PayloadBufferSize is non-zero.


IdeSendData in the IDEOpalSec.c

Function : IdeSendData

File: IDEOpalSec.c
Description:
Send a security protocol command to a device.
Input:
This - Indicates a pointer to the calling context. Type
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL is defined in the
EFI_STORAGE_SECURITY_COMMAND_PROTOCOL description.
MediaId - ID of the medium to send data to.
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.
SecurityProtocolId - Security protocol ID of the security protocol
command to be sent.
SecurityProtocolSpecificData - Security protocol specific portion of
the security protocol command.
PayloadBufferSize - Size in bytes of the payload data buffer.
PayloadBuffer - A pointer to a buffer containing the security protocol
command specific payload data for the security protocol command.
Output:
EFI_SUCCESS - The security protocol command completed successfully.
EFI_UNSUPPORTED - The given MediaId does not support security
protocol commands.
EFI_DEVICE_ERROR - The security protocol command completed with an error.
EFI_INVALID_PARAMETER - The PayloadBuffer or PayloadTransferSize is
NULL and PayloadBufferSize is non-zero.


OpalSecurity.c

Description:
Opal Security Support

The following functions are used in the file: OpalSecurity.c.

Function | Description
InstallOpalSecurityInterface | Installs StorageSecurityProtocol if the drive supports Trusted commands
OpalSecEntryPoint | This function is the entry point for OpalSecurity Driver.
UnInstallOpalSecurityInterface | Uninstalls the Opal Security Init Protocol.


InstallOpalSecurityInterface in the OpalSecurity.c

Function : InstallOpalSecurityInterface

File: OpalSecurity.c
Description:
Installs StorageSecurityProtocol if the drive supports
 Trusted commands
Input:
IN VOID             *BusInterface
IN BOOLEAN          ModeFlag
Output:
EFI_SUCCESS    : StorageSecurity supported.
Others         : Not supported.


OpalSecEntryPoint in the OpalSecurity.c

Function : OpalSecEntryPoint

File: OpalSecurity.c
Description:
This function is the entry point for OpalSecurity
Driver.
Input:
EFI_HANDLE          ImageHandle     Image handle.
EFI_SYSTEM_TABLE    *SystemTable    Pointer to the EFI system table.
Output:
EFI_SUCCESS : OpalSecurity Interface successfully installed.


UnInstallOpalSecurityInterface in the OpalSecurity.c

Function : UnInstallOpalSecurityInterface

File: OpalSecurity.c
Description:
Uninstalls the Opal Security Init Protocol.
Input:
IN VOID             *BusInterface,
IN BOOLEAN          ModeFlag
Output:
EFI_SUCCESS                      : Security Mode supported.
EFI_DEVICE_ERROR/EFI_UNSUPPORTED : Not supported.


OpalSecurity.h

Description:
This file contains the Includes, Definitions, typedefs, Variable
and External Declarations, Structure and function prototypes needed for the
OpalSecurity driver


OpalSecurity.mak

Description:
Make file to build OpalSecurity module


Functions in Alphabetical Order

In Alphabetical Order

The following topics provide a list in alphabetical order.
For a list by file name, see By File Name.

  • A
  • I
  • O
  • R
  • U
Built on 16:45:16 12/28/11


Functions in Alphabetical Order

A

Function | Description
AhciSendData | Send a security protocol command to a device.

Built on 16:45:16 12/28/11


Functions in Alphabetical Order

I

Function | Description
IdeReceiveData | Send a security protocol command to a device that receives data and/or the result of one or more commands sent by SendData.
IdeSendData | Send a security protocol command to a device.
InstallOpalSecurityInterface | Installs StorageSecurityProtocol if the drive supports Trusted commands

Built on 16:45:16 12/28/11


Functions in Alphabetical Order

O

Function | Description
OpalSecEntryPoint | This function is the entry point for OpalSecurity Driver.

Built on 16:45:16 12/28/11


Functions in Alphabetical Order

R

Function | Description
ReceiveData | Send a security protocol command to a device that receives data and/or the result of one or more commands sent by SendData.

Built on 16:45:16 12/28/11


Functions in Alphabetical Order

U

Function | Description
UnInstallOpalSecurityInterface | Uninstalls the Opal Security Init Protocol.

Built on 16:45:16 12/28/11


General Information