Intel

Developer Zone

ProtectedOutput


com.intel.ui
Class ProtectedOutput

java.lang.Object
  extended by 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
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
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