Class FlashStorage
- java.lang.Object
-
- com.intel.util.FlashStorage
-
public class FlashStorage extends java.lang.Object
This class exposes flash storage access APIs for the applets.
Flash data storage is intended for storing only sensitive data and is very limited in size. Its main purpose is for storing private keys and certificates and other small sensitive data. In order to save large amounts of encrypted data, it is recommended to save a key in the flash, encrypt the rest of the data with that key, and save the encrypted data on the main data storage (e.g., the hard drive).
In order to use flash storage, the applet's manifest needs to include the storage access permissions.
The applet data is stored in flash as an encrypted BLOB with integrity protection. Each applet can only access its own flash data. However, different sessions of the same applet share flash resources and access the same files.
To ensure that only one session can access the files in the flash memory, the applet can (optionally) define in the manifest that only one session can be opened for the applet.
Two flash data files per applet are supported (file names: 0, 1). Note that the approved quota in the applet's manifest is the total data size allocated to the applet for both files. It is up to the applet developer to decide whether to use any of the files and how to split the quota between them.
Due to flash wear-out considerations, an applet is allowed to use up to 100 write/erase flash data operations per machine boot. In addition, the applet's allowed operations counter will be reset 24 hours after the applet was installed and every 24 hours since the last write/erase operation.
Note: The data stored in the storage files is lost after the Return To Factory Default (RTFD) process.
Using more than the 256 bytes flash quota requires prior coordination with the Intel DAL team, as it depends on the approval of the platform for reserving more flash storage for Intel DAL.
File Properties
Default values for non-existing file are:
-
-
Field Summary
Fields Modifier and Type Field and Description static int
AR_WITH_MANY_FALSE_DETECTIONS
Anti-Replay (AR) protection has many false detections.static int
AR_WITH_NO_FALSE_DETECTIONS
Anti-Replay (AR) protection has no false detections.static int
AR_WITH_RARE_FALSE_DETECTIONS
Anti-Replay (AR) protection has rare false detections
Anti replay data loss might happen less than 10 times in product lifecycle.static int
FLASH_STORAGE_PROPERTY_ANTI_REPLAY
If property is set to true, the files are stored with anti-replay protection.
-
Method Summary
Methods Modifier and Type Method and Description static void
eraseFlashData(int fileName)
Removes the specified applet file from the flash. Note: After erasing the file, all file properties are restored to default.static int
getAntiReplayType()
Retrieves the Anti-Replay (AR) type supported by this platformstatic int
getFlashDataSize(int fileName)
Returns the size of the specified applet file on the flash.static int
getMaxFileName()
Returns the maximum file name value that can be used in this class.static boolean
getProperty(int fileName, int propertyId)
Returns the value of a specific algorithm property for a given filestatic int
readFlashData(int fileName, byte[] dest, int destOff)
Reads the data from the specified applet file in flash and copies it into the given destination array.static void
setProperty(int fileName, int propertyId, boolean state)
Sets a property that modifies the algorithm behavior for a given file Notes: Properties can only be modified on non-existing files. Properties are saved only after creating a file usingwriteFlashData(int, byte[], int, int)
static void
writeFlashData(int fileName, byte[] src, int srcOff, int srcLen)
Writes the provided data into the specified applet file in the flash.
-
-
-
Field Detail
-
FLASH_STORAGE_PROPERTY_ANTI_REPLAY
public static final int FLASH_STORAGE_PROPERTY_ANTI_REPLAY
If the property is set to True, the files are stored with anti-replay protection. Default: False. Note: There is a limit to the number of files that can be AR-protected. Setting this property might cause writeFlashData to fail to write data, if the maximum number of files that are AR protected has been reached.- See Also:
- Constant Field Values
-
AR_WITH_NO_FALSE_DETECTIONS
public static final int AR_WITH_NO_FALSE_DETECTIONS
Anti-Replay (AR) protection has no false detections.- See Also:
- Constant Field Values
-
AR_WITH_RARE_FALSE_DETECTIONS
public static final int AR_WITH_RARE_FALSE_DETECTIONS
Anti-Replay (AR) protection has rare false detections
Anti replay data loss might happen less than 10 times during the product's lifecycle.- See Also:
- Constant Field Values
-
AR_WITH_MANY_FALSE_DETECTIONS
public static final int AR_WITH_MANY_FALSE_DETECTIONS
Anti-Replay (AR) protection has many false detections.
AR protection is not reliable - possible data loss.
Anti replay data loss might happen more than 10 times during the product's lifecycle.- See Also:
- Constant Field Values
-
-
Method Detail
-
getFlashDataSize
public static int getFlashDataSize(int fileName) throws UtilException
Returns the size of the specified applet file on the flash.- Parameters:
fileName
- the index of the file.getMaxFileName()
indicates the maximum file number value (including) that can be used.- Returns:
- The size of the applet file in flash. For invalid/nonexistent files, the returned size is 0.
- Throws:
IllegalParameterException
- if the file's index is invalid.UtilSecurityException
- if the file was identified as compromised.UtilException
- some internal error occurred.
-
readFlashData
public static int readFlashData(int fileName, byte[] dest, int destOff) throws UtilException
Reads the data from the specified applet file in flash and copies it into the given destination array.- Parameters:
fileName
- the index of the file to read.getMaxFileName()
indicates the maximum file number value (including) that can be used.dest
- the destination array to hold the file datadestOff
- the offset in dest array- Returns:
- The number of bytes copied into destination array.
- Throws:
FileNotFoundException
- if the file doesn't exist.IllegalParameterException
- if the file's index is invalid.UtilSecurityException
- if the file was identified as compromised.UtilException
- an internal error occurred.
-
writeFlashData
public static void writeFlashData(int fileName, byte[] src, int srcOff, int srcLen) throws UtilException
Writes the provided data into the specified applet file in the flash.- Parameters:
fileName
- the index of the file to write.getMaxFileName()
indicates the maximum file number value (including) that can be used.src
- an array holding the data to be copied into the filesrcOff
- the offset in src arraysrcLen
- the length of the data to write- Throws:
AccessDeniedException
- if the size of the new data along with any other flash data already allocated for this applet exceeds the applet flash quota.FlashWearoutException
- if the flash wearout mechanism blocked the write/erase, or if the applet exhausted the number of operations allowed for the current period.UtilOutOfResourcesException
- if one of the following occurs and causes resource exhaustion:- The property
FLASH_STORAGE_PROPERTY_ANTI_REPLAY
was set to True and more than the maximum allowed number of anti-replay files are already being used. - The storage size exceeds the total quota allocated for Intel DAL applets.
- The property
IllegalParameterException
- if the file's index is invalid.UtilSecurityException
- if the file was identified as compromised.UtilException
- in case of internal error.
-
eraseFlashData
public static void eraseFlashData(int fileName) throws UtilException
Removes the specified applet file from the flash. Note: After erasing the file, all file properties are restored to default.- Parameters:
fileName
- the index of the file to remove.getMaxFileName()
indicates the maximum file number value (including) that can be used.- Throws:
FlashWearoutException
- if the flash wearout mechanism blocked the write/erase, or if the applet exhausted the number of operations allowed for the current period.IllegalParameterException
- if the file's index is invalid.FileNotFoundException
- if the file doesn't exist.UtilSecurityException
- if the file was identified as compromised.UtilException
- in case of internal error.
-
setProperty
public static void setProperty(int fileName, int propertyId, boolean state) throws UtilException
Sets a property that modifies the algorithm behavior for a given file Notes:- Properties can only be modified on non existing files.
- Properties are saved only after creating a file using
writeFlashData(int, byte[], int, int)
- Parameters:
fileName
- the index of the file.getMaxFileName()
indicates the maximum file number value (including) that can be used.propertyId
- the property to be set, one of FLASH_STORAGE_PROPERTY_XYZstate
- determines whether the property is enabled or disabled- Throws:
IllegalParameterException
- if one of the following occurs:- the file's index is invalid
- propertyId is unknown
IllegalUseException
- if the fileName already exists and was saved with a different property stateUtilSecurityException
- if the file was identified as compromised.UtilException
- for any other error
-
getProperty
public static boolean getProperty(int fileName, int propertyId) throws UtilException
Returns the value of a specific algorithm property for a given file- Parameters:
fileName
- the index of the file.getMaxFileName()
indicates the maximum file number value (including) that can be used.propertyId
- the property to get, one of FLASH_STORAGE_PROPERTY_XYZ- Returns:
- Returns whether a specific property is disabled or enabled
- Throws:
IllegalParameterException
- if one of the following occurs:- the file's index is invalid
- propertyId is unknown
UtilSecurityException
- if the file was identified as compromised.UtilException
- for any other error
-
getMaxFileName
public static int getMaxFileName()
Returns the maximum file name value that can be used in this class.- Returns:
- The maximum file name value that can be used in this class.
-
-