Intel

Developer Zone

FlashStorage

com.intel.util

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. The main purpose is to store private keys and certificates and other small sensitive data. In order to save large amount of encrypted data, it is recommended to save a key in the flash, encrypt the rest of the data with that key and save it on the main data storage (e.g. hard driver).

    In order to use flash storage, the applet has to have the storage access permissions in its manifest.

    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 are sharing flash resources and access the exact same files. Two flash data files per applet are supported (file name: 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 allowed operations counter will be reset again 24 hours after the applet was installed and every 24 hours since the last write/erase operation.

    Note: The data stored in the storage file(s) will be lost after Return To Factory Default (RTFD) process. Using more than the 256 bytes flash quota requires coordination with DAL team as it depends on the approval of the platform for reserving more flash storage for DAL.

    Note: File state can be:

    • Invalid - The AR counter reset while the file is AR protected.
    • Compromised - DAL detected invalid access to file or compromised behavior.

    File Properties
    Default values for non-existing file are:
    • 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()
      Retrieve the Anti-Replay (AR) type supported by this platform. NOTE: This API is supported only on Gemini Lake (GLK) platforms.
      static 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 file
      static 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 using writeFlashData(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.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, toString
    • Field Detail

      • FLASH_STORAGE_PROPERTY_ANTI_REPLAY

        public static final int FLASH_STORAGE_PROPERTY_ANTI_REPLAY
        If property is set to true, the files are stored with anti-replay protection. Default is false. Note that this resource is limited and setting this property might fail if more than a given amount of anti-replay files are already being used
        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 in product 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 in product 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/non existent files, the returned size will be 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 data
        destOff - the offset in dest array
        Returns:
        The number of bytes copied into dest 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 or invalid.
        UtilException - some 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 file
        srcOff - the offset in src array
        srcLen - 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 resources exhaustion:
        • The property FLASH_STORAGE_PROPERTY_ANTI_REPLAY was set to true and more than a given amount of anti-replay files are already being used.
        • The storage size exceeds the total quota allocated for DAL applets.
        IllegalParameterException - if the file's index is invalid.
        UtilSecurityException - if the file was identified as compromised or invalid.
        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.
      • 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.
      • getAntiReplayType

        public static int getAntiReplayType()
        Retrieve the Anti-Replay (AR) type supported by this platform. NOTE: This API is supported only on Gemini Lake (GLK) platforms.
        Returns:
        The Anti-Replay (AR) type supported by this platform (one of the AR_WITH_* constants)