-------------------------------------------------------------------------------- Matrox Imaging Library (M800DU07) MilMorphis.txt Readme File October 16, 2006 Copyright© 2006 by Matrox Electronic Systems Ltd. All rights reserved. -------------------------------------------------------------------------------- This document explains the current limitations and particularities when using MIL with Matrox Morphis after installing Driver Update 7. It also presents last minute information that did not make it into the manual or on-line help. Note that this text file serves to complement your manual. The information found in this file overrides your formally documented material. Contents 1. Matrox Morphis with MIL. 1.1 What’s new 1.2 Bug fixes and other improvements 1.3 Last minute information 2. Matrox Morphis with ActiveMIL 3. Installation note 4. MorphisChannelSwitching example (new) 1. Matrox Morphis with MIL 1.1 What’s new - Support for image authentication (SHA and RSA). See section 1.3 for more information on using the Matrox Morphis image authentication option. - Support for watchdog on Matrox Morphis Quad. - Support for all versions of Matrox Morphis PC/104-Plus form factor. - Support for all versions of Matrox Morphis PCIe. - New grab firmware on Matrox Morphis Dual: - Support for Matrox Morphis PCIe boards. - New grab firmware on Matrox Morphis Quad: - Support for Matrox Morphis PCIe boards. - The serial port is now compatible with Linux. - New JPEG2000 compression firmware: - Authentication support; - MbufControl(): - Fixed problem with the M_TARGET_SIZE encoding mode. - New UART firmware: - The serial port is now compatible with Linux. 1.2 Bug fixes and other improvements - JPEG2000 - Fixed a possible general protection fault (GPF) when clearing a large (1600x1200 or larger) JPEG2000-compressed buffer using MbufClear(). - Fixed the invalid tags that were inserted in the JPEG2000 code stream when encoding frames using MbufControl() with M_TARGET_SIZE. - Enabled write-combining into the JPEG2000 memory bank. This increases encoding and decoding performance when using buffers located on the host. - Fixed a possible system crash (BSOD) when the Host has insufficient non-paged memory. - Fixed lossless tiled 10-bit compression/decompression. - Fixed lossless 12-bit compression/decompression. - The JPEG2000 function now recovers gracefully when a pipeline decoding error occurs. - Analog Device ADV202 JPEG2000 CODEC - Updated encoding firmware to version 2.9.2, which contains numerous bug fixes. - Matrox Morphis Quad - Fixed a bug where the Matrox Morphis driver did not start when there were other PCI-X to PCI-X bridges in the Host system that used a Matrox Morphis board. - MdigControl(..., M_GRAB_DIRECTION_Y, M_REVERSE) - Fixed a bug where the top-most line of a frame was grabbed as the bottom-most line of the frame. - Fixed a possible system crash (BSOD) when aborting a program in which MdigHookFunction() is used with a non-grab hook such as M_FRAME_START, M_FIELD_START, M_FIELD_START_ODD, or M_FIELD_START_EVEN. 1.3 Last minute information - Msys...() additions: - MsysControl(M_UART_FREE+M_UART_NB(M_DEVn)): - Stops MIL UART operations and frees UART resources used by MIL. - MsysControl(M_CRYPTOGRAPHY_MODE): - Sets whether to use the Matrox Morphis cryptography hardware. When using M_CRYPTOGRAPHY_MODE with M_ENABLE, Matrox Morphis will calculate a SHA-256 fingerprint (hash). Each fingerprint is encrypted using the RSA algorithm with a 1024-bit key while each image is compressed. Note that the compressed image buffers must have cryptography enabled, using MbufControl() with M_CRYPTOGRAPHY set to M_ENABLE. - Available control values: M_ENABLE, M_DISABLE. - MsysControl(M_CRYPTOGRAPHY_P_KEY): - Sets the first secret prime number. When using M_CRYPTOGRAPHY_P_KEY, specify the MIL identifier of a buffer of type M_ARRAY that contains the first secret prime number. - MsysControl(M_CRYPTOGRAPHY_Q_KEY): - Sets the second secret prime number. When using M_CRYPTOGRAPHY_Q_KEY, specify the MIL identifier of a buffer of type M_ARRAY which contains the second secret prime number. - MsysInquire(M_CRYPTOGRAPHY_MODE): - Returns whether or not cryptography mode is enabled on a Matrox Morphis system. - Return values: M_ENABLE, M_DISABLE. - Mbuf...() addition: - MbufControl(M_CRYPTOGRAPHY): - Sets whether the fingerprint is calculated and encrypted for this buffer. When cryptography mode is enabled, a fingerprint is calculated at compression time for each JPEG2000 image buffer. For more information on using JPEG2000, refer to the MIL Reference and the MIL User Guide. - Available control values: M_ENABLE, M_DISABLE. Note that a JPEG2000 image buffer with M_CRYPTOGRAPHY enabled will have the following structure _______________________________________________________________________ | Compressed | Encrypted | Encrypted | Public key | Public key | | Image Data | hash size | hash | size | | |________________|_____________|___________|____________|_____________| |<- M_SIZE_BYTE->|<- 4 bytes ->|<- hash ->|<-4 bytes ->|<- public ->| | | (long) | size | (long) | key size | |________________|_____________|___________|____________|_____________| - MbufInquire(M_CRYPTOGRAPHY): - Returns whether Matrox Morphis will attach an encrypted fingerprint to this image buffer. - Return values: M_ENABLE, M_DISABLE - Using Matrox Morphis for image authentication - To use Matrox Morphis with the authentication option to accelerate the calculation of fingerprints for image authentication, you must use a Matrox Morphis with the authentication option. Each Matrox Morphis with the authentication option can calculate fingerprint at approximately 35 frames/sec. For further information on the image authentication, refer to the Image Authentication with the Matrox Morphis white paper located at http://www.matrox.com/imaging/products/developers_center/home.cfm - Building an image authentication solution using Matrox Morphis - Matrox Morphis has hardware resources to accelerate the fingerprinting portion of the image authentication process. Specifically, Matrox Morphis both generates and encrypts the image fingerprint. However, a third party software library is required to generate both the private and public encryption keys, as well as the decryption and hashing steps used to verify a fingerprint's authenticity. - There are several choices when choosing third-party software library. Note that the following is an incomplete list: - Microsoft's .NET Framework includes a cryptography API. - The CryptoSys libraries (http://www.cryptosys.net). - OpenSSL Crypto library (http://www.openssl.org/source). - BeeCrypt Cryptography Library (http://sourceforge.net/projects/beecrypt/). - Using Matrox Morphis for high-performance image authentication - To use Matrox Morphis as part of a high-performance image authentication solution, you will need to pipeline the fingerprinting and encryption steps of the process. To fingerprint and capture images, use the following steps: 1. Use a third party cryptography library to generate a 1024-bit RSA private/public key pair. For the encryption process, you will need both the p and q secret exponents. 2. Assign the secret exponents p and q to the Matrox Morphis system. Use MsysControl() with M_CRYPTOGRAPHY_P_KEY and a MIL identifier of a M_ARRAY type buffer for secret exponent p. Then use MsysControl() with M_CRYPTOGRAPHY_Q_KEY and a MIL identifier of a M_ARRAY type buffer for secret exponent q. 3. Enable Matrox Morphis hardware fingerprinting and encryption mode by using MsysControl() with M_CRYPTOGRAPHY_MODE set to M_ENABLE. 4. Allocate a list of grab buffers in Matrox Morphis on-board memory using MbufAllocColor() with M_IMAGE + M_GRAB + M_ON_BOARD. 5. Allocate a second list of JPEG2000 image buffers in memory by using MbufAllocColor() with M_IMAGE + M_COMPRESS + M_JPEG2000_LOSSY. You can substitute M_JPEG2000_LOSSLESS for M_JPEG2000_LOSSY to enable lossless JPEG2000 compression. These buffers store the compressed images and fingerprints. Note that several images can be processed concurrently. This requires that several buffers be allocated for this process. 6. Enable fingerprinting for the compressed buffers by using MbufControl() with M_CRYPTOGRAPHY set to M_ENABLE for each buffer. 7. Use MdigProcess() with a hook-handler function to grab and process the frames from your camera as described above (see the MIL reference for more information on using MdigProcess()). Ensure that MdigProcess() grabs images into the previously allocated grab buffer list. The hook-handler function used with MdigProcess() will hook on modifications to the grab buffers. In the hook-handler function, use MthrControl() with M_BUS_MASTER_COPY_MODE set to M_ASYNCHRONOUS to ensure that buffer copy and compression operations are performed asynchronously. Use MbufCopy() to compress, fingerprint and store each frame in a JPEG2000- compressed image buffer into a previously allocated buffer list. 8. (Optional) To save the compressed image buffers to disk after authentication, use MbufHookFunction() with M_MODIFIED_BUFFER for each JPEG2000-compressed image buffer. The hook-handler function is also used to perform any additional processing that is necessary after the images are signed. - Verifying that an image's authenticity - To verify an image's authenticity, use a MIL with a third-party cryptography library using the following steps: 1. Determine the total size of the image to authenticate and copy the image into a MIL buffer. 2. Use MbufInquire() with M_SIZE_BYTE to locate the beginning of the fingerprint portion of the JPEG2000 image file. You can then extract both the encrypted hash and the public encryption key. Note that the JPEG2000 image file has the structure illustrated below: _______________________________________________________________________ | Compressed | Encrypted | Encrypted | Public key | Public key | | Image Data | hash size | hash | size | | |________________|_____________|___________|____________|_____________| |<- M_SIZE_BYTE->|<- 4 bytes ->|<- hash ->|<-4 bytes ->|<- public ->| | | (long) | size | (long) | key size | |________________|_____________|___________|____________|_____________| 3. Decrypt the encrypted hash using the third-party's cryptography library RSA functions and the public key. 4. Generate a new SHA-256 hash of the image in your possession using the cryptography library. 5. Verify the authenticity of the image by comparing the hashes. An authentic image will produce a bit-identical hash to the hash included with the image. 2. Matrox Morphis with ActiveMIL - All the above information also applies to ActiveMIL. - Fast-channel switching - Fixed a possible system crash (BSOD) when fast-channel switching under ActiveMIL. 3. Installation note -During installation, you might be prompted that Matrox Morphis Com Port has not passed Windows Logo testing. This behavior is known and does not affect operations. The installation should be continued. 4. MorphisChannelSwitching example (new) -A new MorphisChannelSwitching example has been added. It is located in the following folder: \Matrox Imaging\Mil\Examples\Board-Specific\Morphis\MorphisChannelSwitching\