Intel

Developer Zone

ProtectedOutput

com.intel.ui

Class ProtectedOutput

  • java.lang.Object
    • com.intel.ui.ProtectedOutput


  • public abstract class ProtectedOutput
    extends java.lang.Object
    The class enables the application to access protected output functionality. It implements crypto functionality enabling to encrypt rendered image and replace encryption key.
    • Field Summary

      Fields
      Modifier and Type Field and Description
      static short AES_CTR_IV_LENGTH
      Supported PAVP crypto counter length.
      static short KEY_LENGTH
      Supported PAVP key length.
      static byte RENDERING_FORMAT_XRGB
      XRGB image format, supported by startRendering method.
    • Method Summary

      Methods
      Modifier and Type Method and Description
      abstract short getEncryptedKeyRecord(byte[] keyStorage, short keyIndex)
      The method retrieves encrypted key record to be provided to GFX driver for key injection.
      abstract int getImageBlock(byte[] data, int index, int maxLength)
      Method enables to retrieve chunk of dialog image to be sent to the host.
      static ProtectedOutput getInstance(int handle, byte[] key, short keyIndex, short keyLength)
      This is a factory method that allows creating an instance of ProtectedOutput.
      abstract short getIV(byte[] buffer, short index)
      This method retrieves the AES counter value that was used for encrypting the rendered image and copies it to the given storage.
      abstract void releaseImage()
      This method releases the internal system rendering buffer in case the applet needs to abort the image data retrieval.
      abstract void setNewKey(byte[] key, short keyIndex, short keyLength)
      This method replaces currently set media encryption key with a new key.
      abstract int startRendering(Dialog dialog, byte format)
      This method processes the provided Dialog object and renders the resulting image in an internal system rendering buffer.
      • Methods inherited from class java.lang.Object

        equals, hashCode, toString
    • Field Detail

      • RENDERING_FORMAT_XRGB

        public static final byte RENDERING_FORMAT_XRGB
        XRGB image format, supported by startRendering method.
        See Also:
        Constant Field Values
      • KEY_LENGTH

        public static final short KEY_LENGTH
        Supported PAVP key length.
        See Also:
        Constant Field Values
      • AES_CTR_IV_LENGTH

        public static final short AES_CTR_IV_LENGTH
        Supported PAVP crypto counter length.
        See Also:
        Constant Field Values
    • Method Detail

      • getInstance

        public static final ProtectedOutput getInstance(int handle,
                                  byte[] key,
                                  short keyIndex,
                                  short keyLength)
                                                 throws UiException
        This is a factory method that allows creating an instance of ProtectedOutput.
        Parameters:
        handle - PAVP handle that was retrieved by the SW application using GFX driver APIs
        key - first key to be used for image encryption (16 bytes)
        keyIndex - index in the key array
        keyLength - length of the key data
        Returns:
        instance of ProtectedOutput class
        Throws:
        UiIllegalParameterException - in one of the following cases:
        • The key provided to the method is invalid.
        • The PAVP handle provided to this method is invalid.
        UiIllegalUseException - if the PAVP session represented by the provided handle is not operating in Heavy mode.
        UiException
      • getIV

        public abstract short getIV(byte[] buffer,
                  short index)
        This method retrieves the AES counter value that was used for encrypting the rendered image and copies it to the given storage. The AES counter is available only after rendering of the Dialog and the right usage will be to call this routine after the Dialog is successfully rendered. The AES counter length is 16 bytes.
        Parameters:
        buffer - byte array to store AES counter, must be at least 16 bytes length
        index - index in the storage array
        Returns:
        the length of the copied data
        Throws:
        UiIllegalUseException - in one of the following cases:
        • If trying to retrieve the AES counter before Dialog is rendered using the startRendering method.
        • If trying to retrieve the AES counter after all image blocks were already retrieved by this applet using the getImageBlock method or releaseImage method was called.
      • getEncryptedKeyRecord

        public abstract short getEncryptedKeyRecord(byte[] keyStorage,
                                  short keyIndex)
        The method retrieves encrypted key record to be provided to GFX driver for key injection. The expected encrypted key size is KEY_LENGTH.
        Parameters:
        keyStorage - array to store encrypted record
        keyIndex - index inside storage array
        Returns:
        length of copied data
      • setNewKey

        public abstract void setNewKey(byte[] key,
                     short keyIndex,
                     short keyLength)
                                throws UiException
        This method replaces currently set media encryption key with a new key. Note that after this method is called, any subsequent calls to startRendering method will use the new key for encrypting the rendered image.
        Parameters:
        key - new media encryption key that should be used from now on by this ProtectedOutput instance
        keyIndex - index in the key array
        keyLength - the length of the new key
        Throws:
        UiIllegalParameterException - if the key size is incorrect. The key is expected to be of KEY_LENGTH size.
        UiException
      • startRendering

        public abstract int startRendering(Dialog dialog,
                         byte format)
                                    throws UiException
        This method processes the provided Dialog object and renders the resulting image in an internal system rendering buffer. getImageBlock method should be used by the applet to retrieve the rendered image block by block. Once this method is called and until all image blocks are retrieved using getImageBlock or released by explicitly calling the releaseImage method, the internal rendering buffer will be locked for other users, and any other call to startRendering method will throw an exception.
        Parameters:
        dialog - applet's dialog to be displayed
        format - graphics rendering format, see RENDERING_FORMAT_... definitions for supported formats.
        Returns:
        the size of the rendered image
        Throws:
        UiOutOfResourcesException - in case the system failed to allocate the internal rendering buffer.
        UiIllegalParameterException - in one of the following cases:
        • The format provided to this method is invalid.
        • The Dialog object provided to this method is invalid. For example, its size is invalid, it does not contain any widgets, etc.
        UiIllegalUseException - in one of the following cases:
        • The internal rendering buffer is currently in use by other application or this application, i.e. startRendering was already called, but the internal system rendering buffer was not released yet by calling releaseImage method or using getImageBlock method to retrieve all rendered image blocks.
        • The Dialog provided to this method contains an Image instance that was created by Image.create(short, XYPair, XYPair, byte) method, but the instance was not updated completely by calling the Image.addBigImageChunk(byte[], int, int) method.
        UiException
      • releaseImage

        public abstract void releaseImage()
                                   throws UiException
        This method releases the internal system rendering buffer in case the applet needs to abort the image data retrieval. After this method is called, another rendering operation can begin by calling startRendering method.
        Throws:
        UiIllegalUseException - in case the rendering buffer is not currently in use by this applet.
        UiException
      • getImageBlock

        public abstract int getImageBlock(byte[] data,
                        int index,
                        int maxLength)
                                   throws UiException
        Method enables to retrieve chunk of dialog image to be sent to the host. The maximum length of the data to be retrieved can be of any size, which is smaller than the total rendered buffer size.
        Parameters:
        data - array to store data
        index - index inside data array
        maxLength - maximum length of data to read
        Returns:
        size of read data
        Throws:
        UiIllegalUseException - in one of the following cases
        • No image was rendered by this applet using the startRendering method before calling this method.
        • The rendering process was completed by this applet by retrieving all image blocks using the getImageBlock method or by calling the releaseImage method.
        UiException