Home

Security Engine 2.x Reference Device Driver User`s Guide: For

1. SEC2_INVALID_CHA_TYPE Requested CHA does not exist in this version of OxEOO4FFFD the hardware SEC2_INVALID_OPERATION_ID Requested opID is out of range for this request OXEOO4FFFC type SEC2_CHANNEL_NOT_AVAILABLE Requested channel was not available This error OxEOO4F FFB exists for legacy compatibility reasons and has no relevance for SEC2 SEC2_CHA_NOT_AVAILABLE Requested CHA was not available at the time the OXE004FFFA request was being processed SEC2_INVALID_LENGTH Length of requested data item is incompatible OXE004FFF9 with request type or data alignment incompatible SEC2_OUTPUT_BUFFER_ALIGNMENT Output buffer alignment incompatible with OxEOO4FFF8 request type SEC2_ADDRESS_PROBLE Driver could not translate argued address into a OXEOO4FFF6 physical address SEC2_INSUFFICIENT_REQS Request entry pool exhausted at the time of OxEQO4FFF5 request processing try again later SEC2_CHA_ERROR CHA flagged an error during processing check OxE004FFF2 the error notification context if one was provided to the request SEC2_NULL_REQUEST Request pointer was argued NULL OXE004FFF1 SEC2_REQUEST_TIMED_OUT Timeout in request processing OxEOO4FFFO SEC2 MALLOC FAILED Direct kernel memory buffer request failed OxEOO4FF
2. Table 30 Table 30 IPSEC_AES CBC REQ Valid Descriptors opld Descriptors Value Function Description DPD_IPSEC_AES_CBC_ENCRYPT_MD5_APAD 0x8000 Perform the IPSec process of encrypting in AES using CBC mode with MD5 auto padding DPD_IPSEC_AES_CBC_ENCRYPT_SHA_APAD 0x8001 Perform the IPSec process of encrypting in AES using CBC mode with SHA 1 auto padding DPD_IPSEC_AES_CBC_ENCRYPT_SHA256_APAD 0x8002 Perform the IPSec process of encrypting in AES using CBC mode with SHA 256 auto padding DPD_IPSEC_AES_CBC_ENCRYPT_MD5 0x8003 Perform the IPSec process of encrypting in AES using CBC mode with MD5 DPD_IPSEC_AES_CBC_ENCRYPT_SHA 0x8004 Perform the IPSec process of encrypting in AES using CBC mode with SHA 1 DPD_IPSEC_AES_CBC_ENCRYPT_SHA256 0x8005 Perform the IPSec process of encrypting in AES using CBC mode with SHA 256 DPD_IPSEC_AES_CBC_DECRYPT_MD5_APAD 0x8006 Perform the IPSec process of decrypting in AES using CBC mode with MD5 auto padding DPD_IPSEC_AES_CBC_DECRYPT_SHA_APAD 0x8007 Perform the IPSec process of decrypting in AES using CBC mode with SHA 1 auto padding DPD_IPSEC_AES_CBC_DECRYPT_SHA256_APAD 0x8008 Perform the IPSec process of decrypting in AES using CBC mode with SHA 256 auto padding DPD_IPSEC_AES_CBC_DECRYPT_MD5 0x8009 Perform the IPSec process of dec
3. 4 66 AES Requests 4 6 1 AESA_CRYPT_REQ COMMON REQ PREAMBLE unsigned long keyBytes 16 24 or 32 bytes unsigned char keyData unsigned long inIvBytes 0 or 16 bytes unsigned char inIvData unsigned long inBytes multiple of 8 bytes unsigned char inData unsigned char outData output length input length unsigned long outCtxBytes 0 or 8 bytes unsigned char outCtxData NUM_AESA_CRYPT_DESC defines the number of descriptors within the DPD AESA CRYPT GROUP that use this request DPD_AESA_CRYPT_GROUP 0x6000 defines the group for all descriptors within this request See Table 17 Table 17 AESA_CRYPT_REQ Valid Descriptors opld Descriptors Value Function Description DPD_AESA_CBC_ENCRYPT_CRYP 0X6000 Perform encryption in AESA using CBC mode DPD_AESA_CBC_DECRYPT_CRYP 0x6001 Perform decryption in AESA using CBC mode DPD_AESA_CBC_DECRYPT_CRYPT_RDK 0x6002 Perform decryption in AESA using CBC mode with RDK DPD_AESA_ECB_ENCRYPT_CRYP 0x6003 Perform encryption in AESA using ECB mode DPD_AESA_ECB_DECRYPT_CRYP 0x6004 Perform decryption in AESA using ECB mode DPD_AESA_ECB_DECRYPT_CRYPT_RDK 0x6005 Perform decryption in AESA using ECB mode with RDK DPD_AESA_CTR_CRYPT 0x6006 Perform CTR in AESA DPD_AESA_CTR_HMAC 0x6007 Perform AES CTR mode cipher operation with integrated authentication as part of the operation 4 7 I
4. Rey Data inBytes nsigned u u u unsigned u unsigned u nsigned DPD RC4 NUM RC4 I char char long inData outData outCtxBytes char outCtxData DREY LOADRI CRYP output length input length 257 bytes EY UNLOADCTX D ULCTX G DPD RC4 DREY CRYP ULCTX G See Table 13 ESC defines the number of descriptors within the ROUP that use this request ROUP 0x3500 defines the group for all descriptors within this request Table 13 ARC4_LOADKEY_CRYPT_UNLOADCTX_REQ Valid Descriptor opld Descriptor Value Function Description DPD_RC4_LDKEY_CRYPT_ULCTX 0x3500 Load the cipher key encrypt using ARC 4 then save the resulting context 4 4 Hash Requests 4 4 1 COMMON_R unsigned unsigned HASH_REQ TG F long char EQ PREAMBLE ctxBytes WCE unsigned unsigned unsigned ong char long Data inBytes inD ata outBytes length is fixed by algorithm Security Engine 2 x Reference Device Driver User s Guide Rev 1 18 Freescale Semiconductor Individual Request Type Descriptions unsigned char outData unsigned char cmpData digest auto compare value NUM_MDHA_DESC defines the number of descriptors within the DPD HASH LDCTX HASH ULCTX GROUP that use this request DPD_HASH_LDCTX_HAS
5. deferred service routine 2 1 5 Deferred Service Routine The ProcessingComplete routine completes the request outside of the interrupt service routine and runs in a non ISR context This routine depends on the IsrMsgQId queue and processes messages written to the queue by the interrupt service routine This function will determine which request is complete and notify the calling task using any handler specified by that calling task It will then check the remaining content of the process request queue and schedule any queued requests Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 5 User Interface 3 User Interface 3 1 Application Interface In order to make a request of the SEC the calling application must populate a request structure with the appropriate information to pass to the driver for processing These structures are described in Section 4 Individual Request Type Descriptions and include items such as operation ID channel callback routines success and error and data Once the request is prepared the application calls ioct 1 with the prepared request This function is a standard system call used by operating system I O subsystems to implement special purpose functions It typically follows the format int ioctl int fd file descriptor int function function code int arg arbitrary argument driver dependent The function code second ar
6. 303 675 2140 Fax 303 675 2150 LDCForFreescaleSemiconductor hibbertgroup com Document Number SEC2XSWUG Rev 1 08 2006 Information in this document is provided solely to enable system and software implementers to use Freescale Semiconductor products There are no express or implied copyright licenses granted hereunder to design or fabricate any integrated circuits or integrated circuits based on the information in this document Freescale Semiconductor reserves the right to make changes without further notice to any products herein Freescale Semiconductor makes no warranty representation or guarantee regarding the suitability of its products for any particular purpose nor does Freescale Semiconductor assume any liability arising out of the application or use of any product or circuit and specifically disclaims any and all liability including without limitation consequential or incidental damages Typical parameters which may be provided in Freescale Semiconductor data sheets and or specifications can and do vary in different applications and actual performance may vary over time All operating parameters including Typicals must be validated for each customer application by customer s technical experts Freescale Semiconductor does not convey any license under its patent rights nor the rights of others Freescale Semiconductor products are not designed intended or authorized for use as components in systems intended for su
7. AFHA ARC 4 hardware accelerator This term is synonymous with AFEU in the Security Engine 2 x chapter of the PowerQUICC device reference manuals and other related documentation APAD Autopad The MDHA will automatically pad incomplete message blocks out to 512 bits when APAD is enabled ARC 4 Encryption algorithm compatible with the RC 4 algorithm developed by RSA Inc Auth Authentication CBC Cipher block chaining An encryption mode commonly used with block ciphers CHA Crypto hardware accelerator This term is synonymous with execution unit in the Security Engine 2 x chapter of the PowerQUICC device reference manuals and other related documentation CTX Context DESA DES accelerator This term is synonymous with DEU in the Security Engine 2 x chapter of the PowerQUICC device reference manuals and other related documentation DPD _ Data packet descriptor ECB Electronic code book An encryption mode less commonly used with block ciphers EU Execution unit HMAC Hashed message authentication code IDGS Initialize digest IPSec Internet protocol security ISR Interrupt service routine MD Message digest synonymous with hash MDHA Message digest hardware accelerator This term is synonymous with MDEU in the Security Engine 2 x chapter of the PowerQUICC device reference manuals and other related documentation OS Operating system PR Public key PRHA Public key hardware accelerator This term is synonymous with PR
8. Perform f9 authentication and finalize digest using existing state DPD REA f9 CIPHER INIT FINAL 0x6105 I Perform f9 authentication and finalize digest using initialized cipher state DPD_KEA_GSM_A53_CIPHER 0x6106 Perform single pass 3GPP GSM A5 3 message processing DPD_KEA_EDGE_A53_CIPHER 0x6107 Perform single pass 3GPP EDGE A5 2 message processing DPD_KEA_f9_CIPHER_FINAL_CMP 0x6108 Perform f9 authentication and finalize digest using existing cipher state Compare final digest with expected value and flag error if they do not match DPD_KEA_f9_CIPHER_INIT_FINAL_CMP 0x6109 Perform f9 authentication and finalize digest using initial cipher state Compare final digest with expected value and flag error if they do not match 4 14 SSL TLS Processing Requests Does not apply to SEC 2 0 Note that there are 4 different classes of requests for SSL TLS message types block or stream cipher either inbound or outbound Since each type has significantly differing content and data mapping into descriptors differs for each type the four separate request types have their own request structure 4 14 1 TLS BLOCR INBOUND REQ COMMON REQ PREAMBLE nsigned long hashKeyBytes nsigned char hashKeyData nsigned long hashOnlyBytes nsigned char hashOnlyData nsigned long ivBytes nsigned char ivData nsigned long cipherKeyBytes nsigned char cipherKeyData nsigned long inBytes nsigned
9. defines the group for all descriptors within this request See Table 34 Table 34 SRTP REQ Valid Descriptors opld Descriptors Value Function Description DPD_SRTP_OUTBOUND 0x8500 Process an outbound SRTP packet DPD_SRTP_INBOUND 0x8501 Process an inbound SRTP packet DPD_SRTP_INBOUND_CMP 0x8502 Process an inbound SRTP packet and compare the signature with an expected value If the compared values differ return an error Does not apply to SEC 2 0 Security Engine 2 x Reference Device Driver User s Guide Rev 1 38 Freescale Semiconductor Individual Request Type Descriptions 4 12 RAID XOR Requests Does not apply to SEC 2 0 4 12 1 COMMON_R u u u u u N RAID_XOR_REQ EQ PR RAMBLE nsigned nsigned nsigned nsigned nsigned UM_RAID request char char char char long inDataA inDataB inDataC outData opSize XOR DESC defines the number of descriptors within the DPD RAID XOR GROUP that use this DPD RAID XOR GROUP 0x6100 defines the group for all descriptors within this request See Table 35 Descriptors Table 35 RAID_XOR_REQ Valid Descriptors opld Value Function Description DPD_RAID_XOR 0x6100 Perform an XOR operation of either 2 or 3 of the input data blocks and write the output 4 13 Kasumi Cipher Requests SEC 2 1 only 4 13 1 COMMON_R u u u u u u u u u
10. u u u DPD Ri NUM RI request nsigned REA CRYPT REQ EQ PR RAMBLE long ivBytes nsigned nsigned nsigned nsigned char long char long ivData keyBytes keyData inBytes multiple of 8 bytes nsigned nsigned nsigned nsigned nsigned nsigned nsigned EBA CRYP BA CRYP1 char long char long char long char inData outBytes outData output length input length if 9_CMP this becomes compare value outIvBytes outIvData ctxBytes ctxData 9 integrity digest context _DESC defines the number of descriptors within the DPD REA CRYPT GROUP that use this GROUP Oxa000 defines the group for all descriptors within this request See Table 36 Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 39 Individual Request Type Descriptions Table 36 REA CRYPT REQ Valid Descriptors opld Descriptors Value Function Description DPD REA f 8 CIPHER INIT 0x6100 Perform f8 cipher function with initial cipher state set DPD_KEA_f8_CIPHER 0x6101 Perform f8 cipher function using cipher state remaining from previous operation DPD_KEA_f9_CIPHER_INIT 0x6102 Perform f9 authentication function with initial state set DPD_KEA_f9_CIPHER 0x6103 Perform f9 authentication function using existing state DPD REA f9 CIPHER FINAL 0x6104
11. 0x7510 Process an inbound IPSec encapsulated system payload packet _SHA_PAD using triple DES in CBC mode and SHA1 with auto padding DPD IPSEC ESP IN TDES CBC DCRPT 0x7511 Process an inbound IPSec encapsulated system payload packet _SHA256_PAD using triple DES in CBC mode and SHA256 with auto padding DPD_IPSEC_ESP_OU DES_ECB_CRPT 0x7512 Process an outbound IPSec encapsulated system payload packet _MD5_PAD using triple DES in ECB mode and MD5 with auto padding DPD_IPSEC_ESP_OU DES_ECB_CRPT 0x7513 Process an outbound IPSec encapsulated system payload packet _SHA_PAD using triple DES in ECB mode and SHA1 with auto padding DPD_IPSEC_ESP_OU DES_ECB_CRPT 0x7514 Process an outbound IPSec encapsulated system payload packet _SHA256_PAD using triple DES in ECB mode and SHA256 with auto padding DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT 0x7515 Process an inbound IPSec encapsulated system payload packet _MD5_PAD using triple DES in ECB mode and MD5 with auto padding DPD IPSEC ESP IN TDES ECB DCRPT 0x7516 Process an inbound IPSec encapsulated system payload packet _SHA_PAD using triple DES in ECB mode and SHA1 with auto padding DPD IPSEC ESP IN TDES ECB DCRPT 0x7517 Process an inbound IPSec encapsulated system payload packet _SHA256_PAD using triple DES in ECB mode and SHA256 with auto padding DPD_IPSEC_ESP_IN_SDES_ECB_DCRPT_MD5 0x7518 Process an inbound IPSec encapsulated system payload packet _PAD_CMP using single DES in ECB mode and MD
12. Completes the user request SEC2 x Execution Operation completed interrupt generated IsrMsgQld execute callback function Writing a message to the queue wakes the ProcessingComplete task If no callback function is defined no callback takes place Figure 1 SEC Device Driver Structure 2 1 1 Driver Initialization Routine The driver initialization routine includes both OS specific and hardware specific initialization The steps taken by the driver initialization routine are as follows e Finds the security engine core and sets the device memory map starting address in ToBaseAddress e Initialize the security engine s registers Controller registers Channel registers Security Engine 2 x Reference Device Driver User s Guide Rev 1 4 Freescale Semiconductor Device Driver Components EU registers e Initializes driver internal variables e Initializes the channel assignment table The device driver will maintain this structure with state information for each channel and user request A mutual exclusion semaphore protects this structure so multiple tasks are prevented from interfering with each other e Initializes the internal request queue This queue holds requests to be dispatched when channels become available The queue can hold up to 16 requests The driver will reject requests with an error when the queue is full e ProcessingComplete is enabled which then pends on IsrmsgQid
13. OCR 1 OUTBOUND DES SH Al 0x9104 Prepare an outbound message using triple DES and SHA1 DPD_TLS OCR 1 OUTBOUND DES_SH A256 0x9105 Prepare an outbound message using triple DES and SHA256 DPD_TLS 1OCK OUTBOUND_A ES MD5 0x9106 Prepare an outbound message using AES and MD5 DPD_TLS OCR OUTBOUND_A ES SHA1 0x9107 Prepare an outbound message using AES and SHA1 DPD_TLS OCR OUTBOUND A ES SHA256 0x9108 Prepare an outbound message using AES and SHA256 4 14 3 COMMON_R nsigned nsigned nsigned nsigned nsigned TLS_STREAM_INBOUND_REQ RAMBLE EQ PR ong char long char long hashKeyBytes has nKeyData hashOnlyBytes hashOn ivBytes nsigned nsigned nsigned nsigned char long char long ivData lyData cipherKeyBytes cipherKeyData inBytes nsigned nsigned nsigned u u u u u u u u u u u u unsigned u nsigned char long long char ong inData MACcmpBytes outBytes outData MACoutBytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 43 Individual Request Type Descriptions unsigned long ivOutBytes unsigned char ivOutData unsigned char cmpData NUM_TLS_STREAM_INBOUND_DESC
14. Process an outbound IPSec encapsulated system payload packet _SHA256_PAD using single DES in ECB mode and SHA256 with auto padding DPD_IPSEC_ESP_IN_SDES_ECB_DCRPT 0x7503 Process an inbound IPSec encapsulated system payload packet _MD5_PAD using single DES in ECB mode and MD5 with auto padding DPD IPSEC ESP IN SDES ECB DCRPT 0x7504 Process an inbound IPSec encapsulated system payload packet _SHA_PAD using single DES in ECB mode and SHA1 with auto padding DPD IPSEC ESP IN SDES ECB DCRPT 0x7505 Process an inbound IPSec encapsulated system payload packet _SHA256_PAD using single DES in ECB mode and SHA256 with auto padding DPD_IPSEC_ESP_OUT_SDES_CBC_CRPT 0x7506 Process an outbound IPSec encapsulated system payload packet _MD5_PAD using single DES in CBC mode and MD5 with auto padding DPD_IPSEC_ESP_OUT_SDES_CBC_CRPT 0x7507 Process an outbound IPSec encapsulated system payload packet _SHA_PAD using single DES in CBC mode and SHA1 with auto padding DPD_IPSEC_ESP_OUT_SDES_CBC_CRPT 0x7508 Process an outbound IPSec encapsulated system payload packet _SHA256_PAD using single DES in CBC mode and SHA256 with auto padding DPD IPSEC ESP IN SDES CBC DCRPT 0x7509 Process an inbound IPSec encapsulated system payload packet _MD5_PAD using single DES in CBC mode and MD5 with auto padding DPD_IPSEC_ESP_IN_SDES_CBC_DCRPT 0x750A Process an inbound IPSec encapsulated system payload packet _SHA_PAD using single DES in CBC mode and SHA1 with
15. REQ Valid Descriptors opld continued 256 PAD CM DPD IPSEC ESP IN SDES CBC DCRPT SHA 0x751d Process an inbound IPSec encapsulated system payload packet 256 PAD CMP using single DES in CBC mode and SHA256 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT_MD5 0x751e Process an inbound IPSec encapsulated system payload packet _PAD_CMP using triple DES in ECB mode and MD5 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT_SHA 0x751f Process an inbound IPSec encapsulated system payload packet _PAD_CMP using triple DES in ECB mode and SHA1 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT_SHA 0x7520 Process an inbound IPSec encapsulated system payload packet 256_PAD_CMP using triple DES in ECB mode andSHA256 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT_MD5 0x7521 Process an inb
16. This serves as the interface between the interrupt service routine and this deferred task 2 1 2 Request Dispatch Routine The request dispatch routine provides the ioct 1 interface to the device driver It uses the callers request code to identify which function is to execute and dispatches the appropriate handler to process the request The driver performs a number of tasks that include tracking requests queuing requests when the requested channel is unavailable preparing data packet descriptors and writing said descriptor s address to the appropriate channel in effect giving the security engine the direction to begin processing the request The ioct1 function returns to the end user application without waiting for the security engine to complete assuming that once a DPD is initiated for processing by the hardware interrupt service may invoke a handler to provide completion notification 2 1 3 Process Request Routine The process request routine translates the request into a sequence of one or more data packet descriptors DPD and feeds it to the security engine core to initiate processing If no channels are available to handle the request the request is queued 2 1 4 Interrupt Service Routine When processing is completed by the security engine an interrupt is generated The interrupt service routine handles the interrupt and queues the result of the operation in the IsrMsgQId queue for deferred processing by the ProcessingComplete
17. add DVX WORKS as one of the definitions Also adding DDBG will assist in the initial driver integration process Once built the driver may simply be downloaded to a running BSP for testing Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 49 Porting 7 3 BSP Integration Once the modules are built they should be linked directly with the user s board support package to become integral part of the board image In VxWorks the file sysLib c contains the initialization functions the memory address space functions and the bus interrupt functions It is recommended to call the function SEC2DriverInit directly from sysLib c In the process of initialization the driver calls a specialized function name sysGetPeripheralBase which returns a pointer to the base location of the peripheral device block in the processor often defined by the CCSBAR register in some PowerQUICC III processors The driver uses this address and an offset to locate the SEC core on the system bus This is not a standard BSP function the integrator will need to provide it or a substitute method for locating CCSBAR The security processor will be initialized at board start up with all the other devices present on the board 8 Porting This section describes probable areas of developer concern with respect to porting the driver to other operating systems or environments At this time this driver
18. caller s operational requirements e All process request structures have a next request member This allows the application to chain multiple process requests together e Itis the application s choice to use a notifier function or to poll the status member to detect completion of the request Security Engine 2 x Reference Device Driver User s Guide Rev 1 6 Freescale Semiconductor User Interface 3 2 Error Handling Due to the asynchronous nature of the device driver there are two primary sources of errors e Syntax or logic These are returned in the status member of the user request argument and as a return code from ioct1 Errors of this type are detected by the driver not by hardware e Protocol procedure These errors are returned only in the status member of the user request argument Errors of this type are detected by hardware in the course of their execution Consequently the end user application needs two levels of error checking the first one after the return from ioct1 and the second after the completion of the request The second level is possible only if the request was done with a validnotify on error handler If the handler has not been specified this level of error will be lost A code example of the two levels of errors are as follows using an AES request as an example AESA_CRYPT_REQ aesdynReq aesdynRed opId DPD AESA CBC ENCRYPT CRYPT aesdynRed channel 0 aesdynReq
19. defined by default as dev sec2 3 3 3 Operation ID opra Masks Operation Ids can be broken down into two parts the group or type of request and the request index or descriptor within a group or type This is provided to help understand the structuring of the opIds It is not specifically needed within a user application See Table 5 Table 5 Request Operation ID Mask Define Description Value DESC_TYPE_MASK The mask for the group or type of an opld OxFEFOO DESC NUM MASR __ The mask for the request index or descriptor within that group or type OxO0FF 3 3 4 Return Codes A complete list of the error status results that may be returned to the callback routines is shown in Table 6 Table 6 Callback Error Status Return Code Code Description Value SEC2_SUCCESS Successful completion of request 0 SEC2_MEMORY_ALLOCATION Driver cannot obtain memory from the host OXE004FFFF operating system SEC2 INVALID CHANNEL Channel specification vvas out of range This OXE004FFFE exists for legacy compatibility and has no relevance for SEC2 Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 9 User Interface Table 6 Callback Error Status Return Code continued
20. defines the number of descriptors within the DPD_TLS_STREAM_INBOUND_GROUP that use this request DPD_TLS_STREAM_INBOUND_GROUP 0x9200 defines the group for all descriptors within this request See Table 39 Table 39 TLS BLOCE INBOUND REQ Valid Descriptors opld Descriptors Value Function Description DPD_TLS_STREAM_INBOUND_MD5 0x9200 Process an inbound message using MD5 and RC4 initial context DPD_TLS_STREAM_INBOUND_CTX_MD5 0x9201 Process an inbound message using MD5 and RC4 external context DPD_TLS_STREAM_INBOUNDS_SHA1 0x9202 Process an inbound message using SHA1 and RC4 initial context DPD_TLS_STREAM_INBOUND_CTX_SHA1 0x9203 Process an inbound message using SHA1 and RC4 external context DPD_TLS_STREAM_INBOUND_SHA256 0x9204 Process an inbound message using SHA256 and RC4 initial context DPD_TLS_STREAM_INBOUND_SHA256 0x9205 Process an inbound message using SHA256 and RC5 external context DPD_TLS_STREAM_INBOUND_MD5_CMP 0x9206 Process an inbound message using MD5 and RC4 initial context Compare digest with external value and return error if digests do not match DPD_TLS_STREAM_INBOUND_CTX_MD5_CMP_ 0x9207 Process an inbound message using MD5 and RC4 external context Compare digest with external value and return error if digests do not match DPD_TLS_STREAM_INBOUNDS_SHA
21. handlers and their proper setup In USERMODE this example also shows one possible means for handling the user to kernel memory transition via the use of three functions for transferring user buffers to and from kernel memory 7 VxWorks Environment The following sections describe the installation of the SEC2 security processor software drivers BSP integration and distribution archives 7 1 Installation To install the software drivers extract the archive containing the driver source files into a suitable installation directory If you want the driver and tests to be part of a standard VxWorks source tree place them as follows Driver WIND_BASE target src drv crypto Tests WIND_BASE target src drv crypto test Once the modules are installed the driver image may be built per the following instructions 7 2 Building the Driver Modules Specific makefiles that can support building of the driver and it s example application are no longer provided due to the differences between the build environment between VxWorks Base 5 and Base 6 For this reason it is assumed that the builder will create a workbench project that builds the driver as a downloadable kernel module and is familiar with this process The driver project will need it s build properties amended to build the driver properly Under Build Properties select the Build Macros tab Within the DEFINES variable
22. initialization Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD SHA224 LDCTX HASH PAD ULCTX CMP 0x450e Compute digest over pre padded data using a SHA224 hash algorithm using an external context Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD_SHA224_LDCTX_IDGS_HASH_PAD_ULCTX_CMP 0x450f Compute digest over pre padded data using SHA224 vvith its standard initialization Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 4 5 HMAC Requests 4 5 1 HMAC_PAD_REQ COMMON_REQ_PREAMBLE nsigned long keyBytes nsigned char keyData nsigned long inBytes nsigned char inData nsigned long outBytes outData cmpData nsigned char cr PE En a P CE T nsigned char length is fixed by algorithm digest auto compare value Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 21 Individual Request Type Descriptions NUM HMAC PAD DESC defines the number of descriptors within the DPD HASH LDCTX HMAC ULCTX GROUP that use this request DPD HASH LDCTX HMAC ULCTX GROUP Ox4A00 defines the group for all descriptors within this request See Table 16 Table 16 HMAC PAD REQ Valid Descriptors o
23. notify void notifAes aesdynReq notify_on_error void notifAes aesdynReq status 0 aesdynReq inIvBytes 16 aesdynReq inIvData iv_in aesdynReq keyBytes 32 aesdynReq keyData Aeskey aesdynRed inBytes packet_length aesdynReq inData aesData aesdynReq outData aesResult aesdynReq outIvBytes 16 aesdynReq outIvData iv Out aesdynReq nextReq 0 status Ioctl device IOCTL_PROC_REQ amp aesdynReq if status 0 printf Syntax Logic Error in dynamic descriptor 0x x n status Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 7 User Interface in callback function notifAes if printf 3 3 3 3 aesdynReq status 1 0 Error detected by HN 0x x n aesdynReq status Global Definitions I O Control Codes The I O control code is the second argument in the ioct 1 function Definitions of these control codes are defined in Sec2 h Internally these values are used in conjunction with a base index to create the I O control codes The macro for this base index is defined by SEC2 IOCTL INDEX and has a default value of 0x0800 See Table 3 Table 3 Second and Third Arguments to ioct1 I O Control Code Second Purpose of ioct 1 Function Argumen
24. proc devices then the shell command to accomplish this would normally appear as mknod c 254 0 dev sec2 Once this is done user tasks can make requests to the driver under the device name dev sec2 6 2 Operation 6 2 1 Driver Operation in Kernel Mode Operation of the SEC 2x core under kernel mode is relatively straightforward Once the driver module has loaded which will initialize the device direct calls to the ioct 1 entry named SEC2_ioct1 in the driver can be made the first two arguments may effectively be ignored In kernel mode request completion may be handled through the standard use of notification callbacks in the request The example suite available with the driver shows how this may be accomplished this suite uses a mutex that the callback will release in order to allow the request to complete although the caller may make use of any other type of event mechanism that suits their preference Logical to physical memory space translation is handled internal to the driver 6 2 2 Driver Operation in User Mode Operation of the SEC 2x core in user mode is slightly more complex than in kernel mode In particular the transition from user to kernel memory space creates two complications for user mode operation e User memory buffers can t be passed directly to the driver instead in this driver edition the user must allocate and place data in kernel memory buffer for operation This can be accomplished via SEC2_MA
25. process of encrypting in triple DES using ECB mode with SHA 1 padding DPD_IPSEC_ECB_TDES_ENCRYPT_SHA256 0x7108 Perform the IPSec process of encrypting in triple DES using ECB mode with SHA 256 padding DPD_IPSEC_ECB_TDES_DECRYPT_MD5 0x7109 Perform the IPSec process of decrypting in triple DES using ECB mode with MD5 padding DPD_IPSEC_ECB_TDES_DECRYPT_SHA 0x710A_ Perform the IPSec process of decrypting in triple DES using ECB mode with SHA 1 padding DPD_IPSEC_ECB_TDES_DECRYPT_SHA256 0x710B Perform the IPSec process of decrypting in triple DES using ECB mode with SHA 256 padding 4 9 3 IPSEC_AES CBC_REQ unsigned long hashKeyBytes unsigned char hashKeyData unsigned long cryptKeyBytes unsigned char cryptKeyData unsigned long cryptCtxInBytes unsigned char cryptCtxInData unsigned long hashInDataBytes unsigned char hashInData unsigned long inDataBytes unsigned char inData unsigned char cryptDataOut Security Engine 2 x Reference Device Driver User s Guide Rev 1 32 Freescale Semiconductor unsigned long hashDataOutBytes unsigned char hashDataOut NUM_IPSEC_AES Individual Request Type Descriptions CBC_DESC defines the number of descriptors within the DPD IPSEC AES CBC GROUP that use this request DPD_IPSEC_A ES_CBC_GROUP 0x8000 defines the group for all descriptors within this request See
26. section Note that the user may wish to reorganize header file locations consistent with the file location conventions appropriate for their system configuration See Table 42 Table 42 Reference Driver Files Header Description Sec2 h Primary public header file for all users of the driver Sec2Driver h Driver hardware interfaces private to the driver itself Sec2Descriptors h DPD type definitions Sec2Notify h Structures for ISR main thread communication sec2 dpd Table h DPD construction constants sec2_cha c CHA mapping and management sec2_dpd c DPD construction functionality sec2_init c Device driver initialization code sec2_io c Basic register I O primitives sec2_ioctl c Operating system interfaces sec2_request c Request response management sec2_sctrMap c Scatter buffer identification and mapping sec2isr c Interrupt service routine Security Engine 2 x Reference Device Driver User s Guide Rev 1 52 Freescale Semiconductor 9 Revision History Table 43 provides a revision history for this document Table 43 Revision History Revision History Rev Number Date Substantive Change s 0 10 18 2005 Initial Release 1 08 17 2006 Tested support for 2 2 core Full dynamic configuration for the SEC Added support for PKEU modular inverse operations Added two descriptor AES CMAC examples Security Engine 2 x Reference Device Driver User s Guide R
27. ue ae 47 VxWorks Environment u e ue Lee 49 e POUE ai ea ede tieta ad cs GE gi gia 50 5 REVISION History ce esa cicio sas asror ioti 53 xe oL Z treescale semiconductor Overview Table 1 Product and SEC Core Version Product Family Device SEC Core Version SE 2x Driver Features Not Supported in Silicon PowerQUICC II Pro MPC8323E SEC 2 2 Public Key Kasumi RNG ARC 4 MPC8343E MPC8347E MPC8349E SEC 2 0 Rasumi XOR single descriptor SSL TLS Rev 1 1 MPC8343EA MPC8347EA SEC 2 4 Kasumi MPC8349EA Rev 3 MPC8358E MPC8360E Rev 1 SEC 2 0 Kasumi XOR single descriptor SSL TLS MPC8358EA MPC8360EA Rev 2 SEC 2 4 Kasumi PowerQUICC III MPC8541E MPC8555E SEC 2 0 Kasumi XOR single descriptor SSL TLS MPC8543E MPC8545E MPC8547E SEC 2 1 MPC8548E The driver is coded in ANSI C In it s design an attempt has been made to write a device driver that is as operating system agnostic as practical Where necessary operating system dependencies are identified and the Porting section addresses them Testing has been accomplished on VxWorks 5 5 and LinuxPPC using kernel version 2 6 11 Application interfaces to this driver are implemented through the ioct1 function call Requests made through this interface can be broken down into specific components including miscellaneous requests and process requests The miscellaneous requests are any requests not related t
28. unsigned char hashKeyData unsigned long cryptKeyBytes unsigned char cryptKeyData unsigned long cryptCtxInBytes unsigned char cryptCtxInData unsigned long hashInDataBytes unsigned char hashInData unsigned long inDataBytes unsigned char inData unsigned char cryptDataOut unsigned long hashDataOutBytes unsigned char hashDataOut NUM_IPSEC_CBC_D request Security Engine 2 x Reference Device Driver User s Guide Rev 1 ESC defines the number of descriptors within the DPD IPSI EC_CBC_GROUP that use this 30 Freescale Semiconductor DPD IPSI Individual Request Type Descriptions EC CBC GROUP 0x7000 defines the group for all descriptors within this request See Table 28 Table 28 IPSEC_CBC_REQ Valid Descriptors opid Descriptors Descriptor Value Function Description DPD_IPSEC_CBC_SDES_ENCRYPT_MD5 0x7000 Perform the IPSec process of encrypting in single DES using CBC mode with MD5 padding DPD_IPSEC_CBC_SDES_ENCRYPT_SHA 0x7001 Perform the IPSec process of encrypting in single DES using CBC mode with SHA 1 padding DPD IPSEC CBC SDES ENCRYPT SHA256 0x7002 Perform the IPSec process of encrypting in single DES using CBC mode with SHA 256 padding DPD_IPSEC_CBC_SDES_DECRYPT_MD5 0x7003 Perform the IPSec process of decrypting in single DES using CBC mode with MD5 padding DPD
29. variable so that the developer can turn message sources on or off as required This global is named SEC2DebugLevel and contains an OR ed combination of any of the bits shown in Table 41 Table 41 Debug Messages Bit Description DBGTXT SETRQ Messages from request setup operations new requests inbound from the application DBGTXT SVCRQ Messages from servicing device responses ISR deferred service routine handlers outbound to the application DBGTXT INITDEV Messages from the device driver initialization process Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 51 Porting Table 41 Debug Messages continued Bit Description DBGTXT_DPDSHOW Shows the content of a constructed DPD before it is handed to the security core DBGTXT_INFO Shows a short banner at device initialization describing the driver and hardware version DBGTXT_DATASHOW Displays the content of all DPD referenced data buffers before the request is passed to the hardware DBGTXT_DESCBUE Displays contents of the descriptor buffer after processing to show what was fetched by the hardware In normal driver operation not in a development setting the DBG definition should be left undefined for best performance 8 6 Distribution Archive For this release the distribution archive consists of the source files listed in this
30. 1_CMP 0x9208 Process an inbound message using SHA1 and RC4 initial context Compare digest with external value and return error if digests do not match DPD_TLS_STREAM_INBOUND_CTX_SHA1_CMP 0x9209 Process an inbound message using SHA1 and RC4 external context Compare digest with external value and return error if digests do not match DPD_TLS_STREAM_INBOUND_SHA256_CMP 0x920a Process an inbound message using SHA256 and RC4 initial context Compare digest with external value and return error if digests do not match DPD_TLS_STREAM_INBOUND_SHA256_CMP 0x920b Process an inbound message using SHA256 and RC4 external context Compare digest with external value and return error if digests do not match 4 14 4 TLS_STREAM_OUTBOUND_REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 44 Freescale Semiconductor Sample Code unsigned char hashKeyData unsigned long ivBytes unsigned char ivData unsigned long cipherKeyBytes unsigned char cipherKeyData unsigned long hashOnlyBytes unsigned char hashOnlyData unsigned long mainDataBytes unsigned long outBytes unsigned char outData unsigned long MACbytes unsigned long i
31. 5 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_SDES_ECB_DCRPT_SHA 0x7519 Process an inbound IPSec encapsulated system payload packet _PAD_CMP using single DES in ECB mode and SHA1 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_SDES_ECB_DCRPT_SHA Ox751a_ Process an inbound IPSec encapsulated system payload packet 256_PAD_CMP using single DES in ECB mode andSHA256 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_SDES_CBC_DCRPT_MD5 0x751b Process an inbound IPSec encapsulated system payload packet _PAD_CMP using single DES in CBC mode and MD5 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_SDES_CBC_DCRPT_SHA 0x751c Process an inbound IPSec encapsulated system payload packet using single DES in CBC mode and SHA1 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 Security Engine 2 x Reference Device Driver User s Guide Rev 1 36 Freescale Semiconductor Individual Request Type Descriptions Table 32 IPSEC ESP
32. CK_INBOUND_SDES_SHA1_SMAC 0x900e Process inbound message using single DES and SHA1 SMAC DPD_TLS_BLOCK_INBOUND_SDES_SHA1_SMAC_CMP Ox900f Process inbound message using single DES and SHA1 SMAC and comparing signatures with the expected value returning an error if a mismatch occurs Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 41 Individual Request Type Descriptions Table 37 TLS_BLOCK_INBOUND_REQ Valid Descriptors opld continued DPD_TLS_BLOCK_INBOUND_TDES_MD5_SMAC 0x9010 Process inbound message using triple DES and MD5 SMAC DPD_TLS_BLOCK_INBOUND_TDES_MD5_SMAC_CMP 0x9011 Process inbound message using triple DES and MD5 SMAC and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_TDES_SHA1_SMAC 0x9012 Process inbound message using triple DES and SHA1 SMAC DPD_TLS_BLOCK_INBOUND_TDES_SH1_SMAC_CMP 0x9013 Process inbound message using triple DES and SHA1 SMAC and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_AES_MD5 0x9014 Process inbound message using AES and MD5 DPD_TLS_BLOCK_INBOUND_AES_MD5_CMP 0x9015 Process inbound message using single AES and MD5 and comparing signatures with the expected va
33. DCTX HASH ULCTX 0x4409 Compute a final SHA224 digest with autopadding and an external context Does not apply to SEC 2 0 DPD SHA224 LDCTX IDGS HASH ULCTX 0x440a Compute an interim SHA224 digest using autopadding and use the algorithm s standard initialization Does not apply to SEC 2 0 DPD SHA224 CONT HASH ULCTX 0x440b J Compute an interim SHA224 digest using autopadding and use an external context Does not apply to SEC 2 0 DPD_SHA256_LDCTX_HASH_ULCTX_CMP 0x440c Compute a final SHA256 digest using autopadding and an external context Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD_MD5_LDCTX_HASH_ULCTX_CMP 0x440d Compute a final MD5 digest using autopadding and an external context Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD_SHA_LDCTX_HASH_ULCTX_CMP 0x440e Compute a final SHA1 digest using autopadding and an external context Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 19 Individual Request Type Descriptions Table 14 HASH REQ Valid Descriptors 0x4400 opid continued DPD SHA256_LDCTX_IDGS_HASH_ULCTX_CMP Ox440f Compute an interim SHA256 digest using autopadding and use the algorithm s standar
34. D_TDES_CBC_ENCRYPT_SA_LDCTX_CRYPT desencReq channel 0 dynamic channel desencReq notify void notifyDes callback function desencReq notify_on_error void notifyDes callback in case of errors only desencRegq status 0 desencReq ivBytes 8 input iv length desencReq ivData iv in pointer to input iv desencReq keyBytes 24 key length desencReq keyData DesKey pointer to key desencReq inBytes packet_length data length desencReq inData DesData pointer to data desencReq outData desEncResult pointer to results desencReq nextReq 0 no descriptor chained call the driver status Ioctl device IOCTL PROC REQ amp desencReq First Level Error Checking if status 0 void notifyDes void Second Level Error Checking if desencRegq status 0 5 2 IPSEC Sample define User Requests structures IPSEC_CBC_REQ ipsecReq Tpsec dynamic descriptor triple DES with SHA 1 authentication ipsecReq opId DPD_IPSEC_CBC_TDES_ENCRYPT_SHA_PAD ipsecReq channel 0 ipsecReq notify void notifyFunc ipsecReq notify_on_error void notifyFunc ipsecReq status 0 ipsecReq hashKeyBytes 16 key length for HMAC SHA 1 ipsecReg hashKeyData authKey pointer to HMAC Key ipsecReg cryptCtxInBytes 8 length of input iv ipsecReg cryptCtxInData in_iv pointe
35. EE SEC2 FREE FAILED Direct kernel memory free failed OxEOO4FFEE SEC2 PARITY SYSTEM ERROR Parity Error detected on the bus OXE004FFED SEC2 INCOMPLETE POINTER Error due to partial pointer OXE004FFEC SEC2 TEA ERROR A transfer error has occurred OXE004FFEB SEC2 FRAGMENT POOL EXHAUSTED The internal scatter gather buffer descriptor pool OXE004FFEA is full SEC2 FETCH FIFO OVERFLON Too many DPDs written to a channel indicates OxE004FFE9 an internal driver problem SEC2 BUS MASTER ERROR Processor could not acquire the bus for a data 0xE004FFE8 transfer SEC2 SCATTER LIST ERROR Caller s list describing a scatter gather buffer is OxE004FFE 7 corrupt SEC2 UNRNONN ERROR Any other unrecognized error OXE004FFE6 SEC2 IO CARD NOT FOUND Error due to device hardware not being found 1000 SEC2 IO MEMORY ALLOCATE ERROR Error due to insufficient resources 1001 SEC2 IO IO ERROR Error due to I O configuration 1002 Security Engine 2 x Reference Device Driver User s Guide Rev 1 10 Freescale Semiconductor User Interface Table 6 Callbach Error Status Return Code continued SEC2 IO VXNORRS DRIVER TABLE ADD ERROR Error due to VxWorks not being able to add 1003 driver to table SEC2 IO INTERRUPT ALLOCATE ERROR Error due to interrupt allocation error 1004 SEC2 VXNORRS CANNOT CREATE QUEUE Error due to VxWorks not being able to cre
36. ES using ECB mode DPD_SDES_ECB_DECRYPT 0x2601 Decrypt data in single DES using ECB mode DPD TDES ECB ENCRYPT 0x2602 J Encrypt data in triple DES using ECB mode DPD TDES ECB DECRYPT 0x2603 I Decrypt data in triple DES using ECB mode 4 3 ARC4 Requests 4 3 1 ARC4_LOADCTX_CRYPT_REQ COMMON_REQ_ PRI RAMBLE unsigned long inCtxBytes unsigned char inCtxData unsigned long inBytes 257 bytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 17 Individual Request Type Descriptions unsigned unsigned unsigned unsigned NUM RC4 I DPD RC4 char char long char LDCTX inD ata outData outCtxBytes outCtxData CRYP output length input length 257 bytes LOADCTX_UNLOADCTX_D ULCTX_G DPD_RC4 LDCTX CRYP ULCTX_G See Table 12 ESC defines the number of descriptors within the ROUP that use this request ROUP 0x3400 defines the group for all descriptors within this request Table 12 ARC4 LOADCTX CRYPT REQ Valid Descriptor opld Descriptor Value Function Description DPD_RC4_LDCTX_CRYPT_ULCTX 0x3400 Load context encrypt using ARC 4 and store the resulting context 4 3 2 ARC4_LOADKEY_CRYPT_UNLOADCTX_REQ RAMBLE F COMMON_R nsigned nsigned nsigned EQ PR long char long keyBytes
37. EU in the Security Engine 2 x chapter of the PowerQUICC device reference manuals and other related documentation RDK J Restore decrypt key An AESA option to re use an existing expanded AES decryption key RNGA Random number generator accelerator SDES Single DES TEA Transfer error acknowledge TDES Triple DES VxWorks Operating system provided by Wind River Systems Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 3 Device Driver Components 2 Device Driver Components This section is provided to help users understand the internal structure of the device driver 2 1 Device Driver Structure Internally the driver is structured in four basic components e Driver Initialization and Setup e Application Request Processing e Interrupt Service Routine e Deferred Service Routine While executing a request the driver runs in system kernel state for all components with the exception of the ISR which runs in the operating system s standard interrupt processing context Figure 1 shows the SEC Reference Device Driver structure End User Application Driver Prepare request invoked Driver Code non blocking ioctl e Tracks Requests e Queue Request when Channels are Unavailable Callback function e Prepare Descriptors Driver e Start the descriptor s execution in a channel returns Operation starts ProcessingComplete Task Sleeps on queue
38. Freescale Semiconductor Users Guide Security Engine 2 x SEC2xSWUG Rev 1 08 2006 Reference Device Driver User s Guide For SEC 2 x Device Driver Version 1 6 1 Overview This document is a user s guide for the SEC 2 x Reference Device Driver version 1 6 SEC 2 x refers to the integrated security engine found in most members of the PowerQUICC JI Pro and PowerQUICC III device families The SEC 2 x Reference Device Driver version 1 6 is a superset device driver including all the routines necessary to operate the acceleration features available in the SEC 2 1 the most capable SEC core found in PowerQUICC products today The SEC 2 0 2 2 and 2 4 cores offer a subset of SEC 2 1 functionality and consequently not all the examples of application interaction with the SEC 2 x core will apply to all PowerQUICC devices Table 1 shows the SEC core version found in each member of the PowerQUICC product family Consult the individual PowerQUICC device s reference manual to determine which SEC core and functions are applicable to your environment Freescale Semiconductor Inc 2005 2006 All rights reserved OmANIDUN FWN Contents ee VERVIEW nit ince na dat para hala gegen idea 1 Device Driver Components 4 4 8 User Interface Leica sc sas hagas emails 6 Individual Request Type Descriptions 16 of Sample CODE sco n a e Dt cance Abs Saya 45 Linux Environment o ue
39. H_ULCTX_GROUP 0x4400 defines the group for all descriptors within this request See Table 14 Table 14 HASH_REQ Valid Descriptors 0x4400 opid Descriptors Value Function Description DPD_SHA256_LDCTX_HASH_ULCTX 0x4400 Compute a final SHA256 digest using autopadding and an external context DPD_MD5_LDCTX_HASH_ULCTX 0x4401 Compute a final MD5 digest using autopadding and an external context DPD_SHA_LDCTX_HASH_ULCTX 0x4402 Compute a final SHA1 digest using autopadding and an external context DPD_SHA256_LDCTX_IDGS_HASH_ULCTX 0x4403 Compute an interim SHA256 digest using autopadding and use the algorithm s standard initialization DPD_MD5_LDCTX_IDGS_HASH_ULCTX 0x4404 Compute an interim MD5 digest using autopadding and use the algorithm s standard initialization DPD_SHA_LDCTX_IDGS_HASH_ULCTX 0x4405 Compute an interim SHA1 digest using autopadding and use the algorithm s standard initialization DPD_SHA256_CONT_HASH_ULCTX 0x4406 Compute an interim SHA256 digest using autopadding and use an external context DPD_MD5_CONT_HASH_ULCTX 0x4407 Compute an interim MD5 digest using autopadding and use an external context DPD_SHA_CONT_HASH_ULCTX 0x4408 Compute an interim SHA1 digest using autopadding and use an external context DPD SHA224 L
40. LLOC SEC2_FREE SEC2_COPYFROM and SEC2_COPYTO requests see Section 3 3 1 I O Control Codes for more information CAUTION Extreme caution must be exercised by the user in transferring memory in this fashion kernel memory space may easily be corrupted by the caller causing target system instability Security Engine 2 x Reference Device Driver User s Guide Rev 1 48 Freescale Semiconductor VxWorks Environment e Standard notification callbacks cannot work since the routines to perform the callback are in user memory space and cannot safely execute from kernel mode In their place standard POSIX signals can be used to indicate I O completion by placing the process ID of the user task in the notification members of the request and flagging NOTIFY_IS_PID in the notifyFlags member The driver uses SIGUSR1 to indicate normal request completions and SIGUSR2 to indicate error completions The example suite available with the driver illustrates the contrast between the two different application environments Within the testAl1 c file there is a set of functions that shows the difference between the two operations Building the example testing application with __KERNEL__ on building a kernel mode test shows the installation and usage of standard completion callbacks and a mutex used for interlock Conversely building the example testing application with USERMODE turned on shows the installation of signal
41. NDL Install an auxiliary deferred service handler for a channel that was reserved by ER IOCTL_RESERVE_CHANNEL_STATIC This exists so that the application using a reserved channel may implement it s own channel completion interrupt handler to be invoked at the completion of operations on a channel Will be passed an argument to an AUX_HANDLER_SPEC which will include the channel number and a pointer to the handler to be installed or NULL if the handler is to be disabled Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor User Interface 3 3 2 Channel Definitions The NUM_CHANNELS definition is used to specify the number of channels implemented in the SEC2 device If not specified it will be set to a value of 4 as a default See Table 4 Table 4 Channel Defines Define Description UM_AFHAS Number of ARC4 accelerators UM DESAS Number of DES accelerators UM_MDHAS Number of message digest accelerators UM_RNGAS Number of random number generators UM_PKHAS Number of public key accelerators 22 23 2323 23 Z UM_AESAS Number of AES accelerators NUM_KEAS Number of Kasumi accelerators The NuM CHAS definition contains the total number of crypto hardware accelerators CHAS in SEC2 and is simply defined as the sum of the individual channels The device name is
42. SEC_AES_ECB_ENCRYPT_SHA_APAD 0x8101 Perform the IPSec process of encrypting in AES using ECB mode with SHA 1 auto padding DPD_IPSEC_AES_ECB_ENCRYPT_SHA256_APAD 0x8102 Perform the IPSec process of encrypting in AES using ECB mode with SHA 256 auto padding DPD_IPSEC_AES_ECB_ENCRYPT_MD5 0x8103 Perform the IPSec process of encrypting in AES using ECB mode with MD5 DPD_IPSEC_AES_ECB_ENCRYPT_SHA 0x8104 Perform the IPSec process of encrypting in AES using ECB mode with SHA 1 DPD_IPSEC_AES_ECB_ENCRYPT_SHA256 0x8105 Perform the IPSec process of encrypting in AES using ECB mode with SHA 256 DPD_IPSEC_AES_ECB_DECRYPT_MD5_APAD 0x8106 Perform the IPSec process of decrypting in AES using ECB mode with MD5 auto padding DPD_IPSEC_AES_ECB_DECRYPT_SHA_APAD 0x8107 Perform the IPSec process of decrypting in AES using ECB mode with SHA 1 auto padding DPD_IPSEC_AES_ECB_DECRYPT_SHA256_APAD 0x8108 Perform the IPSec process of decrypting in AES using ECB mode with SHA 256 auto padding DPD_IPSEC_AES_ECB_DECRYPT_MD5 0x8109 Perform the IPSec process of decrypting in AES using ECB mode with MD5 DPD_IPSEC_AES_ECB_DECRYPT_SHA 0x810A Perform the IPSec process of decrypting in AES using ECB mode with SHA 1 DPD_IPSEC_AES_ECB_DECRYPT_SHA256 0x810B Perform the IPSec process of decrypting in AES using ECB mode with SHA 256 4 9 5 IPSEC_ESP_REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes unsigned char hashKeyData unsigned lon
43. TX_RRMODP_ULCTX 0x5300 Compute the result of an RRMODP operation 4 7 5 MOD_INV_REQ COMMON REQ PREAMBLE nsigned long nBytes nsigned char inData nsigned long inBytes nsigned char inData u u u u unsigned long outBytes u nsigned char outData NUM_MM_MOD_INV_DESC defines the number of descriptors within the DPD MM MOD INV ULCTX GROUP that use this request DPD MM MOD INV ULCTX GROUP 0x5500 defines the group for all descriptors within this request See Table 22 Table 22 MOD INV REQ Valid Descriptor opid Descriptor Value Function Description DPD_MM_MOD_INV_ULCTX 0x5500 Compute the modular inverse of inData using the modulus specified in inData Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 25 Individual Request Type Descriptions 4 7 6 MOD 2OP REQ nsigned long bDataBytes nsigned char bData nsigned long aDataBytes nsigned char aData nsigned long modBytes nsigned char modData u u u u u u unsigned long outBytes u nsigned char outData NUM_MM_20P_DESC defines the number of descriptors within the DPD MM LDCTX 20P ULCTX GROUP that use this request DPD MM LDCTX 20P ULCTX GROUP 0x5400 defines the group for all descriptors within this request See Table 23 Table 23 MOD_20P_REQ Valid Descriptors opld Descr
44. _IPSEC_CBC_SDES_DECRYPT_SHA 0x7004 Perform the IPSec process of decrypting in single DES using CBC mode with SHA 1 padding DPD_IPSEC_CBC_SDES_DECRYPT_SHA256 0x7005 Perform the IPSec process of decrypting in single DES using CBC mode with SHA 256 padding DPD IPSEC CBC TDES ENCRYPT MD5 0x7006 Perform the IPSec process of encrypting in triple DES using CBC mode with MD5 padding DPD_IPSEC_CBC_TDES_ENCRYPT_SHA 0x7007 Perform the IPSec process of encrypting in triple DES using CBC mode with SHA 1 padding DPD_IPSEC_CBC_TDES_ENCRYPT_SHA256 0x7008 Perform the IPSec process of encrypting in triple DES using CBC mode with SHA 256 padding DPD_IPSEC_CBC_TDES_DECRYPT_MD5 0x7009 Perform the IPSec process of decrypting in triple DES using CBC mode with MD5 padding DPD_IPSEC_CBC_TDES_DECRYPT_SHA 0x700A Perform the IPSec process of decrypting in triple DES using CBC mode with SHA 1 padding DPD_IPSEC_CBC_TDES_DECRYPT_SHA256 0x700B Perform the IPSec process of decrypting in triple DES using CBC mode with SHA 256 padding 4 9 2 IPSEC_ECB_REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes unsigned char hashKeyData unsigned long cryptKeyBytes unsigned char cryptKeyData unsigned long hashInDataBytes unsigned char hashInData unsigned long inDataBytes unsigned char inData unsigned long hashDataOutBytes unsigned char hashDataOut unsigned char cryptDataOut Security Engine 2 x Reference Device Driver User
45. annel out of the pool of channels available for general processing This feature may be desirable in the instance that a channel may be needed for rapid servicing of data peculiar to a specific protocol with high real time demand requirements Requesting a channel is done with the IocTL_RESERVE_CHANNEL_STATIC Call It s argument is a pointer to a channel byte that will be used in the channel argument for all subsequent requests Once the static channel is no longer needed it can be returned to the free channel pool with tocTL_RELEASE_CHANNEL 3 3 8 1 Reserved Channel Specification Normal requests to the driver take place through the common_REQ_PREAMBLE to the detailed request block The channel argument in this block is normally left at zero and if specified as such the driver allocates a channel on a round robin basis for each request as it comes in extra requests become placed in a queue for each channel If the channel specification is nonzero for example from 1 to 4 for all SEC 2 x devices other that are not 2 2 then the driver will post the request to that channel if the channel is reserved to that requestor 3 3 8 2 Auxiliary Channel Service Handlers Should a reserved channel need the ability to invoke a special handler at the end of processing for a given request then an auxiliary handler routine may be installed to service end of processing events for that channel T
46. ar AO to B1 MUL1 operation DPD POLY LDCTX AO B1 MUL2 ULCTX 0x5411 Perform a modular A to B MUL2 operation DPD POLY LDCTX AO B1 ADD ULCTX 0x5412 Perform a modular AO to B1 ADD operation DPD_POLY_LDCTX_A1_B1_MUL1_ULCTX 0x5413 Perform a modular A1 to B1 MUL1 operation DPD_POLY_LDCTX_A1_B1_MUL2_ULCTX 0x5414 Perform a modular A1 to B1 MUL2 operation Security Engine 2 x Reference Device Driver User s Guide Rev 1 26 Freescale Semiconductor Individual Request Type Descriptions Table 23 MOD_20P_REQ Valid Descriptors opld continued Descriptors Value Function Description DPD POLY LDCTX_A1_B1 ADD_ULCTX 0x5415 Perform a modular A1 to B1 ADD operation DPD POLY LDCTX_A2_B1 MUL1_ULCTX 0x5416 Perform a modular A2 to B1 MUL1 operation DPD POLY LDCTX_A2_B1 MUL2_ULCTX 0x5417 Perform a modular A2 to B1 MUL2 operation DPD POLY LDCTX_A2_B1 ADD_ULCTX 0x5418 Perform a modular A2 to B1 ADD operation DPD POLY LDCTX_A3_B1 MUL1_ULCTX 0x5419 Perform a modular A3 to B1 MUL1 operation DPD POLY LDCTX_A3_B1 MUL2_ULCTX Ox541A Perform a modular A3 to B1 MUL2 operation DPD POLY LDCTX_A3_B1 ADD_ULCTX 0x541B Perform a modular A3 to B1 ADD operation DPD POLY LDCTX AO B2 MUL1 ULCTX 0x541C Perform a modula
47. ate 1009 the ISR queue in LOInitQs SEC2_CANCELLED_REQUEST Error due to canceled request 1010 SEC2 INVALID ADDRESS Error due to a NULL request 1011 3 3 5 Miscellaneous Request Structures STATUS REQ Structure Used to indicate the internal state of the sEC2 core as well as the driver after the occurrence of an event Returned as a pointer by Get Status and embedded in all requests This structure is defined in Sec2Notify h Each element is a copy of the contents of the same register in the SEC2 driver This structure is also known as SEC2_STATUS through a typedef nsigned long ChaAssignmentStatusRegister 2 nsigned long InterruptControlRegister 2 nsigned long InterruptStatusRegister 2 nsigned long IdRegister nsigned long ChannelStatusRegister NUM_CHANNELS 2 nsigned long ChannelConfigurationRegister NUM_CHANNELS 2 nsigned long CHAInterruptStatusRegister NUM_CHAS 2 nsigned long QueueEntryDepth nsigned long FreeChannels nsigned long FreeAfhas nsigned long FreeDesas nsigned long FreeMdhas nsigned long FreePkhas nsigned long FreeAesas nsigned long FreeKeas GG SER O E Er O AG EG AG 0 ies e nsigned long BlockSize SEC2_NOTIFY_ON_ERROR_CTX Structure Structure returned to the not ify_on_error callback routine that was setup in the initial process request This structure contains the original request structure as well as an er
48. ation DPD POLY LDCTX_A1_B3 MUL1_ULCTX 0x542B Perform a modular A1 to B3 MUL1 operation DPD POLY LDCTX_A1_B3 MUL2_ULCTX 0x542C Perform a modular A1 to B3 MUL2 operation DPD POLY LDCTX_A1_B3 ADD_ULCTX 0x542D Perform a modular A1 to B3 ADD operation DPD POLY LDCTX_A2_B3 MUL1_ULCTX 0x542E Perform a modular A2 to B3 MUL1 operation DPD POLY LDCTX_A2_B3 MUL2_ULCTX 0x542F Perform a modular A2 to B3 MUL2 operation DPD POLY LDCTX_A2_B3 ADD_ULCTX 0x5430 Perform a modular A2 to B3 ADD operation DPD POLY LDCTX_A3_B3 MUL1_ULCTX 0x5431 Perform a modular A3 to B3 MUL1 operation DPD POLY LDCTX A3 B3 MUL2 ULCTX 0x5432 Perform a modular A3 to B3 MUL2 operation DPD POLY LDCTX A3 B3 ADD ULCTX 0x5433 Perform a modular A3 to B3 ADD operation Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 27 Individual Request Type Descriptions 4 8 4 8 1 COMMON R u u u u u u u u u u u u NUM nsigned nsigned nsigned nsigned nsigned nsigned nsigned nsigned nsigned nsigned nsigned nsigned ECC POINT REQ EQ PREAMBLE ong nDataBytes char nData ong eDataBytes char eData ong buildDataBytes char buildData ong blDataBytes char blDa
49. auto padding DPD IPSEC ESP IN SDES CBC DCRPT 0x750B Process an inbound IPSec encapsulated system payload packet _SHA256_PAD using single DES in CBC mode and SHA256 with auto padding DPD_IPSEC_ESP_OUT_TDES_CBC_CRPT 0x750C Process an outbound IPSec encapsulated system payload packet D5_PAD using triple DES in CBC mode and MD5 with auto padding Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 35 Individual Request Type Descriptions Table 32 IPSEC ESP REQ Valid Descriptors opld continued _PAD_CMP DPD_IPSEC_ESP_OU DES_CBC_CRPT 0x750D Process an outbound IPSec encapsulated system payload packet _SHA_PAD using triple DES in CBC mode and SHA1 with auto padding DPD_IPSEC_ESP_OU DES_CBC_CRPT Ox750E Process an outbound IPSec encapsulated system payload packet _SHA256_PAD using triple DES in CBC mode and SHA256 with auto padding DPD IPSEC ESP IN TDES CBC DCRPT Ox750F Process an inbound IPSec encapsulated system payload packet _MD5_PAD using triple DES in CBC mode and MD5 with auto padding DPD IPSEC ESP IN TDES CBC DCRPT
50. catter references shall be marked in the request s scatterBufs element Which bits get marked shall be determined by a helper function that understands the mapping used on an individual request basis 3 3 7 1 Building the Local Scatter gather List with EXT_SCATTER_ELEMENT Since individual operating systems shall have their own internal means defining memory mapping constructs the driver cannot be designed with specific knowledge of one particular mapping method Therefore a generic memory fragment definition structure EXT_SCATTER_ELEMENT is defined for this purpose Each EXT_SCATTER_ELEMENT describes one contiguous fragment of user memory and is designed so that multiple fragments can be tied together into a single linked list Each element has the aspects shown in Table 8 Table 8 Scatter_Gather_Elements Aspects of Scatter_Gather_Elements Description void next Pointer to next fragment in list NULL if at end of list void fragment Pointer to contiguous data fragment unsigned short size Size of this fragment in bytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 13 User Interface With this the caller must construct the list of all the fragments needed to describe the buffer NULL terminate the end of the list and pass the head as the buffer pointer argument This list must remain intact until co
51. char inData nsigned long MACcmpBytesl nsigned long outBytes nsigned char outData nsigned long MACoutBytes Gy Ge a le GS GG GES ES GG Gs T Es GS nsigned long ivOutBytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 40 Freescale Semiconductor Individual Request Type Descriptions unsigned char ivOutData NUM TLS B DPD TLS B OCR INBOUND DESC defines the number of descriptors within the OCR INBOUND GROUP that use this request DPD TLS BLOCR INBOUND GROUP 0x9000 defines the group for all descriptors within this request See Table 37 Table 37 TLS BLOCR INBOUND REQ Valid Descriptors opld Descriptors Value Function Description DPD_TLS_BLOCK_INBOUND_SDES_MD5 0x9000 Process inbound message using single DES and MD5 DPD_TLS_BLOCK_INBOUND_SDES_MD5_CMP 0x9001 Process inbound message using single DES and MD5 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_SDES_SHA1 0x9002 Process inbound message using single DES and SHA1 DPD_TLS_BLOCK_INBOUND_SDES_SHA1_CMP 0x9003 Process inbound message using single DES and SHA1 and comparing signatures with the expected value r
52. d initialization Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD MD5_LDCTX_IDGS_HASH_ULCTX_CMP 0x4410 Compute an interim MD5 digest using autopadding and use the algorithm s standard initialization Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD SHA_LDCTX_IDGS_HASH_ULCTX_CMP 0x4411 Compute an interim SHA1 digest using autopadding and use the algorithm s standard initialization Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD SHA224 LDCTX HASH ULCTX CMP 0x4412 Compute a final SHA224 digest using autopadding and an external context Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD SHA224 LDCTX IDGS HASH ULCTX CMP 0x4413 Compute an interim SHA224 digest using autopadding and use the algorithm s standard initialization Compare the digest to an expected value and flag an error if they do not compare Does not apply to SEC 2 0 DPD NUM MDHA PAD DI HASH LDCTX HASH PAD ULCTX GROU DPD HASH LDCTX HASH PAD ULCTX GROU request See Table 15 ESC defines the number of descriptors within the P that use this request P 0x4500 defines the group for all descriptors vvithin t
53. e the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD_SHA256_LDCTX_HMAC_PAD_ULCTX_CMP 0x4a0b Compute a SHA256 HMAC digest over a pre padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD_MD5_LDCTX_HMAC_PAD_ULCTX_CMP 0x4a0c Compute an MD5 HMAC digest over a pre padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD_SHA_LDCTX_HMAC_PAD_ULCTX_CMP 0x4a0d Compute a SHA1 HMAC digest over a pre padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD SHA224 LDCTX HMAC ULCTX CMP 0x40ae Compute a SHA224 HMAC digest over a non padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD_SHA224_LDCTX_HMAC_PAD_ULCTX_CMP Ox4a0f Compute a SHA224 HMAC digest over a pre padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 Security Engine 2 x Reference Device Driver User s Guide Rev 1 22 Freescale Semiconductor Individual Request Type Descriptions
54. escale Semiconductor 37 Individual Request Type Descriptions NUM CCMP DESC defines the number of descriptors within the DPD CCMP GROUP that use this request DPD CCMP GROUP 0x6500 defines the group for all descriptors within this request See Table 33 Table 33 CCMP_REQ Valid Descriptors opld Descriptors Value Function Description DPD_802_11_CCMP_OUTBOUND 0X6500 Process an outbound CCMP packet DPD 802 11 CCMP INBOUND 0x6501 Process an inbound CCMP packet DPD_802_11_CCMP_INBOUND_CMP 0X6502 Process an inbound CCMP packet and compare the packet signature with an expected value If they don t compare return an error Does not apply to SEC 2 0 4 11 SRTP Protocol Requests 4 11 1 COMMON_R nsigned nsigned nsigned nsigned nsigned SRTP_REQ 10 PR RAMBLE long char long char long hashReyBytes hashKeyData keyBytes keyData ivBytes nsigned nsigned char long ivData HeaderBytes nsigned u u u u u u u u unsigned unsigned unsigned unsigned unsigned unsigned unsigned u nsigned NUM SRTP long char long long char long char long char _DESC inBytes inData ROCBytes cryptDataBytes cryptDataOut digestBytes digestData outIvBytes outIvData defines the number of descriptors within the DPD SRTP GROUP that use this request DPD SRTP GROUP 0x8500
55. eturning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_SDES_SHA256 0x9004 Process inbound message using single DES and SHA256 DPD_TLS_BLOCK_INBOUND_SDES_SHA256_CMP 0x9005 Process inbound message using single DES and SHA256 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_TDES_MD5 0x9006 Process inbound message using triple DES and MD5 DPD_TLS_BLOCK_INBOUND_TDES_MD5_CMP 0x9007 Process inbound message using triple DES and MD5 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_TDES_SHA1 0x9008 Process inbound message using triple DES and SHA1 DPD_TLS_BLOCK_INBOUND_TDES_SHA1_CMP 0x9009 Process inbound message using triple DES and SHA1 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_TDES_SHA256 0x900a Process inbound message using triple DES and SHA256 DPD_TLS_BLOCK_INBOUND_TDES_SHA256_CMP 0x900b Process inbound message using triple DES and SHA256 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_SDES_MD5_SMAC 0x900c Process inbound message using single DES and MD5 SMAC DPD_TLS_BLOCK_INBOUND_SDES_MD5_SMAC_CMP_ Ox900d Process inbound message using single DES and MD5 SMAC and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLO
56. ev 1 Freescale Semiconductor 53 Revision History THIS PAGE INTENTIONALLY LEFT BLANR Security Engine 2 x Reference Device Driver User s Guide Rev 1 54 Freescale Semiconductor Revision History THIS PAGE INTENTIONALLY LEFT BLANR Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 55 How to Reach Us Home Page www freescale com email support freescale com USA Europe or Locations Not Listed Freescale Semiconductor Technical Information Center CH370 1300 N Alma School Road Chandler Arizona 85224 1 800 521 6274 480 768 2130 support freescale com Europe Middle East and Africa Freescale Halbleiter Deutschland GmbH Technical Information Center Schatzbogen 7 81829 Muenchen Germany 44 1296 380 456 English 46 8 52200080 English 49 89 92103 559 German 33 1 69 35 48 48 French support freescale com Japan Freescale Semiconductor Japan Ltd Headquarters ARCO Tower 15F 1 8 1 Shimo Meguro Meguro ku Tokyo 153 0064 Japan 0120 191014 81 3 5437 9125 support japan freescale com Asia Pacific Freescale Semiconductor Hong Kong Ltd Technical Information Center 2 Dai King Street Tai Po Industrial Estate Tai Po N T Hong Kong 800 2666 8080 support asia freescale com For Literature Requests Only Freescale Semiconductor Literature Distribution Center P O Box 5405 Denver Colorado 80217 1 800 441 2447
57. g cryptKeyBytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 34 Freescale Semiconductor Individual Request Type Descriptions unsigned char cryptKeyData unsigned long cryptCtxInBytes unsigned char cryptCtxInData unsigned long hashInDataBytes unsigned char hashInData unsigned long inDataBytes unsigned char inData unsigned char cryptDataOut unsigned long hashDataOutBytes unsigned char hashDataOut unsigned long cryptCtxOutBytes unsigned char cryptCtxOutData NUM IPSEC ESP DESC defines the number of descriptors within the DPD IPSEC ESP GROUP that use this request DPD IPSEC ESP GROUP 0x7500 defines the group for all descriptors within this request See Table 32 Table 32 IPSEC ESP REQ Valid Descriptors opld Descriptors Value Function Description DPD IPSEC ESP OUT SDES ECB CRPT 0x7500 Process an outbound IPSec encapsulated system payload packet _MD5_PAD using single DES in ECB mode and MD5 with auto padding DPD_IPSEC_ESP_OUT_SDES_ECB_CRPT 0x7501 Process an outbound IPSec encapsulated system payload packet _SHA_PAD using single DES in ECB mode and SHA1 with auto padding DPD_IPSEC_ESP_OUT_SDES_ECB_CRPT 0x7502
58. gument is defined as the Section 3 3 1 I O Control Codes This code will specify the driver specific operation to be performed by the device in question The third argument is the pointer to the SEC user request structure which contains information needed by the driver to perform the function requested The following is a list of guidelines to be followed by the end user application when preparing a request structure e The first member of every request structure is an operation ID op1p The operation ID is used by the device driver to determine the format of the request structure e All requests have a channel member It should normally be specified as zero and as such the driver will place the request on the next available channel from the pool of channels in use If the requesting task has reserved a static channel for dedicated use numbered 1 or higher this member may be filled in with the number of the reserved channel e All process request structures have a status member This value is filled in by the device driver when the interrupt for the operation occurs and it reflects the status of the completed operation as determined by the deferred service routine e All process request structures have two notify members notify and notify_on_error These notify members can be used by the device driver to notify the application when its request has been completed They may be the same function or different as required by the
59. har modData unsigned long outBytes unsigned char outData NUM DPD 4 8 3 EC_2OP_DI Individual Request Type Descriptions ESC defines the number of descriptors within the DPD EC 20P GROUP that use this request _EC_20P_GROUP 0x5900 defines the group for all descriptors within this request See Table 25 Table 25 ECC_20P_REQ Valid Descriptors opld Descriptor Value Function Description DPD EC_F2M_LDCTX_MUL1_ULCTX 0x5900 Perform an F2M MULT1 operation ECC_SPKBUILD_REQ ry COMMON REQ PREAMBL nsigned nsigned nsigned nsigned nsigned nsigned nsigned char nsigned 1 char nsigned 1 char nsigned 1 char nsigned 1 char nsigned 1 char a0 a0 al ral a2 a2 a3 Fad bo b0 bl b1 long ong ong ong ong ong u u u u u u u u u u u u u u nsigned NUM nsigned 1 char EC_SPKBUI ong D D DataBytes Data DataBytes Data DataBytes Data DataBytes Data DataBytes Data DataBytes Data this request DPD_ EC_SPKBUI buildDataBytes buildData ESC defines the number of descriptors within the DPD EC SPRBUILD GROUP that use D GROUP Ox5a00 defines the group for all descriptors within this request See Table 26 Table 26 ECC_SPKBUILD_REQ Valid Descriptor opId De scriptor Value Function Descripti
60. has been ported to function on both VxWorks and Linux operating systems Most of the internal functionality is independent of the constructs of a specific operating system but there necessarily are interface boundaries between them where things must be addressed Only a few of the files in the driver s source distribution contain specific dependencies on operating system components this is intentional Those specific files are as follows Sec2Driver h sec2_init c sec2 io c 8 1 Header Files Sec2Driver h This header file is meant to be local private to the driver itself and as such is responsible for including all needed operating system header files and casts a series of macros for specific system calls Of particular interest this header casts local equivalents macros for the follovving malloc Allocate a block of system memory with the operating system s heap allocation mechanism free Return a block of memory to the system heap semGive Release a mutex semaphore semTake Capture and hold a mutex semaphore Security Engine 2 x Reference Device Driver User s Guide Rev 1 50 Freescale Semiconductor Porting 8 2 C Source Files Sec2 dnitec sec2 init c performs the basic initialization of the device and the driver It is responsible for finding the base address of the hardware and saving it in IOBaseAddress for later reference For Linux this file also contains references to register unregister the driver as a kernel
61. hat handler may be installed or disabled through the use of tocTL_INSTALL_AUX_HANDLER Which is passed a pointer to a Aux HANDLER SPEC which specifies the channel to service and a pointer to the user s handler to execute the service typedef struct int auxHandler int ch void regs char channel AUX_HANDLER_SPEC In any case channel should always be the channel that is reserved for use If it is not reserved an error will be returned The auxHandler pointer references the user handler function When dispatched by the driver it will be passed two items 1 the number of the channel whose interrupt triggered this handler and 2 a pointer to a copy of a DEVICE REGS as saved from the ISR as it s argument so that the handler can act on any error information that was saved Although the auxiliary handler is cast to return an int as a status value this return is ignored by the driver at this time Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 15 Individual Request Type Descriptions If auxHandler is passed as a nuru value then an existing handler will be disabled This should be accomplished before a channel is released NOTE Auxiliary handlers run in a deferred service context not in the context of the calling application For this reason they need to complete in a reasonable amount of time to prevent starving other channels from service Al
62. hat use rX GROUP 0x2500 defines the group for all descriptors within this request See Table 10 Table 10 DES_CBC_CRYPT_REQ Valid Descriptors opId Descriptors Value Function Description DPD_SDES_CBC_CTX_ENCRYP 0x2500 Load encrypted context from a dynamic channel to encrypt in single DES using CBC mode DPD_SDES_CBC_CTX_DECRYP 0x2501 Load encrypted context from a dynamic channel to decrypt in single DES using CBC mode DPD_TDES_CBC_CTX_ENCRYP 0x2502 Load encrypted context from a dynamic channel to encrypt in triple DES using CBC mode DPD_TDES_CBC_CTX_DECRYP 0x2503 Load encrypted context from a dynamic channel to decrypt in triple DES using CBC mode 4 2 2 DES_CRYPT_REQ COMMON REQ PREAMBLE unsigned long keyBytes 8 16 or 24 bytes unsigned char keyData unsigned long inBytes multiple of 8 bytes unsigned char inData unsigned char outData output length input length NUM_DES_DESC defines the number of descriptors within the DPD DES ECB GROUP that use this request DPD_DES_ECB_GROUP 0x2600 defines the group for all descriptors within this request See Table 11 Table 11 DES CRYPT REQ Valid Descriptors opld Descriptors Value Function Description DPD_SDES_ECB_ENCRYPT 0x2600 Encrypt data in single D
63. his Table 15 HASH_REOQ Valid Descriptors 0x4500 opid Descriptors Value Function Description 9 PD SHA256 LDCTX HASH PAD ULCTX 0x4500 Compute digest over pre padded data using a SHA 256 hash algorithm with an external context DPD_MD5_LDCTX_HASH_PAD_ULCTX 0x4501 Compute digest over pre padded data using an MD5 hash algorithm with an external context DPD_SHA_LDCTX_HASH_PAD_ULCTX 0x4502 Compute digest over pre padded data using a SHA 1 hash algorithm with an external context O PD_SHA256_LDCTX_IDGS_HASH_PA D_ULCTX 0x4503 Compute digest over pre padded data using SHA 256 with its standard initialization DPD_MD5_LDCTX_IDGS_HASH_PAD_ULCTX 0x4504 Compute digest over pre padded data using MD5 with its standard initialization DPD_SHA_LDCTX_IDGS_HASH_PAD_ULCTX 0x4505 Compute digest over pre padded data using SHA1 with its standard initialization DPD SHA224 LDCTX HASH PAD ULCTX 0x4506 J Compute digest over pre padded data using a SHA224 hash algorithm with an external context Does not apply to SEC 2 0 DPD_SHA224_LDCTX_IDGS_HASH_PAD_ULCTX 0x4507 Compute digest over pre padded data using SHA224 with its standard initialization Does not apply to SEC 2 0 Security Engine 2 x Reference Device Driver User s Guide Rev 1 20 Freescale Semiconductor Individual Request Type Description
64. iptors Value Function Description DPD_MM_LDCTX_MUL1_ULCTX 0x5400 Perform a modular MUL1 operation DPD_MM_LDCTX_MUL2_ULCTX 0x5401 Perform a modular MUL2 operation DPD_MM_LDCTX_ADD_ULCTX 0x5402 Perform a modular ADD operation DPD_MM_LDCTX_SUB_ULCTX 0x5403 Perform a modular SUB operation DPD_POLY_LDCTX_AO_BO_MUL1_ULCTX 0x5404 Perform a modular AO to BO MUL1 operation DPD_POLY_LDCTX_AO_BO_MUL2_ULCTX 0x5405 Perform a modular AO to BO MUL2 operation DPD_POLY_LDCTX_AO_BO_ADD_ULCTX 0x5406 Perform a modular AO to BO ADD operation DPD_POLY_LDCTX_A1_BO_MUL1_ULCTX 0x5407 Perform a modular A1 to BO MUL1 operation DPD_POLY_LDCTX_A1_BO_MUL2_ULCTX 0x5408 Perform a modular A1 to BO MUL2 operation DPD_POLY_LDCTX_A1_BO_ADD_ULCTX 0x5409 Perform a modular A1 to BO ADD operation DPD POLY LDCTX A2 BO MUL1 ULCTX 0x540A Perform a modular A2 to BO MUL1 operation DPD POLY LDCTX A2 BO MUL2 ULCTX 0x540B Perform a modular A2 to BO MUL2 operation DPD POLY LDCTX A2 BO ADD ULCTX 0x540C Perform a modular A2 to BO ADD operation DPD POLY LDCTX A3 B0 MUL1 ULCTX 0x540D Perform a modular A3 to BO MUL1 operation DPD POLY LDCTX A3 B0 MUL2 ULCTX 0x540E Perform a modular A3 to BO MUL2 operation DPD POLY LDCTX A3 BO ADD ULCTX 0x540F Perform a modular A3 to BO ADD operation DPD POLY LDCTX AO B1 MUL1 ULCTX 0x5410 Perform a modul
65. lue returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_AES_SHA1 0x9016 Process inbound message using single AES and SHA1 DPD_TLS_BLOCK_INBOUND_AES_SHA1_CMP 0x9017 Process inbound message using single AES and SHA1 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_AES_SHA256 0x9018 Process inbound message using single AES and SHA256 DPD_TLS_BLOCK_INBOUND_AES_SHA256_CMP 0x9019 Process inbound message using single AES and SHA256 and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_AES_MD5_SMAC 0x901a Process inbound message using single AES and MD5 SMAC DPD_TLS_BLOCK_INBOUND_AES_MD5_SMAC_CMP 0x901b Process inbound message using single AES and MD5 SMAC and comparing signatures with the expected value returning an error if a mismatch occurs DPD_TLS_BLOCK_INBOUND_AES_SHA1_SMAC 0x901c Process inbound message using single AES and SHA1 SMAC DPD_TLS_BLOCK_INBOUND_AES_SHA1_SMAC_CMP_ 0x901d Process inbound message using single AES and SHA1 SMAC and comparing signatures with the expected value returning an error if a mismatch occurs 4 14 2 TLS BLOCR OUTBOUND REQ COMMON REQ PREAMBLE nsigned long hashKeyBytes nsigned char hashKe
66. mask that specifies which of the argued buffers are mapped through a scatter gather list The mask is filled out via the driver s helper function MarkScatterBuf fer described in the discussion on scatter gather buffer management notifyFlags If a POSIX style signal handler will be responsible for request completion notification then it can contain ORed bits of NOTIFY IS PIDand orNOTIFY ERROR IS PID signifying that the notifyornotify on error pointers are instead the process ID s i e getpid ofthe task requesting a signal upon request completion channel identifies the channel to be used for the request Should normally be zero and as such the driv er places the request on the next available channel or queues the request If a static channel has been reserved pass it s number here to ensure that the request executes on this channel only notify pNotifyCtx notify_on_error pointer to a notification callback routine that will be called when the request has completed suc cessfully May instead be a process ID if a user state signal handler will flag completion see notifyFlags for more info pointer to context area to be passed back through the notification routine pointer to the notify on error routine that will be called when the request has completed unsuc cessfully May instead be a process ID if a user state signal handler will flag completion see notifyFlags for more info Securit
67. module and to manage it s usage link count sec2_io c sec2_io c contains functions to establish e Channel interlock semaphores IoInitSemaphores e The ISR message queue IOInitQs e Driver service function registration with the operating system IORegisterDriver e ISR connection disconnection IoCconnect Interrupt 8 3 Interrupt Service Routine The ISR will queue processing completion result messages onto the IsrMsgQId queue ProcessingComplete pends on this message queue When a message is received the completion task will execute the appropriate callback routine based on the result of the processing When the end user application prepares the request to be executed callback functions can be defined for nominal processing as well as error case processing If the callback function was set to NULL when the request was prepared then no callback function will be executed These routines will be executed as part of the device driver so any constraints placed on the device driver will also be placed on the callback routines 8 4 Conditional Compilation See the makefile for specifics on the default build of the driver 8 5 Debug Messaging The driver includes a pBG define that allows for debug message output to the developer s console If defined in the driver build debug messages will be sent from various components in the driver to the console Messages come from various sections of the driver and a bitmask is kept in a driver global
68. mpletion of the request 3 3 7 2 Scatter Buffer Marking For reasons of legacy compatibility the structure of all driver request types maintains the same size and form as prior versions with a minor change in that a size compatible scatterBufs element was added as a modification to the channel element in other versions This allows the caller a means of indicating which buffers in the request are scatter composed as opposed to direct contiguous memory for instance key data could be in contiguous system memory while ciphertext data will be in fragmented user memory A problem with marking buffers using this method is that there is no means for the caller to clearly identify which bit in scatterBufs matches any given pointer in the request since the data description portion of different requests cannot be consistent or of any particular order A helper function MarkScatterBuf fer is therefore made available by the driver to make the bit pointer association logic in the driver accessible to the caller It s form is MarkScatterBuffer void request void buffer where request points to the request block being built the opra element must be set prior to call and buffer points to the element within the request which references a scattered buffer It will then mark the necessary bit in scatterBufs that defines this buffer for this specific request type 3 3 7 3 Direct Scatter Gather Usage Example In order to make this usage clear a
69. n example is presented Assume that a triple DES encryption operation is to be constructed where the input and output buffers are located in fragmented user memory and the cipher keys and IV are contained in system memory A DES_LOADCTX_CRYPT_REQ is zero allocated as encReq and constructed set up encryption operation encReq oplid DPD_TDES_CBC_CTX_ENCRYPT encReq notify notifier encReq notify_on_error notifier encReq inIvBytes 8 ncReq keyBytes 24 encReq inBytes bufsize encReq inIvData iv encReq keyData cipherRey encReq inData unsigned char input this buffer is scattered encReq outIvBytes 8 encReq outIvData VCEX encReq outData unsigned char output this buffer is scattered MarkScatterBuffer amp encRegq amp encReq input MarkScatterBuffer amp encReg amp encReq output Security Engine 2 x Reference Device Driver User s Guide Rev 1 14 Freescale Semiconductor User Interface Upon completion of the two mark calls encReq scatterBufs will have two bits set within it that the driver knows how to interpret as meaning that the intended buffers have scatter lists defined for them and will process them accordingly as the DPD is built for the hardware 3 3 8 Reserved Channels Beginning with driver version 1 5 a capability is added to allow a task the ability to reserve a channel and use it separately from other requests i e keeps that ch
70. ncluded with the distribution assumes this inclusion As delivered this directory is defined as kernelroot drivers sec2 Once the driver source is installed and the kernel source and modules are built module dependency lists updated and the built objects are installed in the target filesystem the driver named sec2drv o is ready for loading when needed Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 47 Linux Environment 6 1 2 Device Inode Kernel processes may call the driver s functionality directly On the other hand user processes must use the kernel s I O interface to make driver requests The only way for user processes to do this it to open the device as a file with the open system call to get a file descriptor and then make requests through ioct1 Thus the system will need a device file created to assign a name to the device The driver functions as a char device in the target system As shipped the driver assumes that the device major number will be assigned dynamically and that the minor number will always be zero since only one instance of the driver is supported Creation of the device s naming inode may be done manually in a development setting or may be driven by a script that runs after the driver module loads and before any user attempts to open a path to the driver Assuming the module loaded with a dynamically assigned major number of 254 look for sec2 in
71. nteger Public Key Requests 4 7 1 MOD_EXP_REQ COMMON_REQ_PR unsigned long unsigned RAMBLE unsigned long unsigned unsigned long unsigned aDataBytes char aData expBytes char expData modBytes char modData Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 23 Individual Request Type Descriptions unsigned long outBytes unsigned char outData NUM_MM_EXP_DESC defines the number of descriptors within the DPD MM LDCTX EXP ULCTX GROUP that use this request DPD MM LDCTX EXP ULCTX GROUP 0x5100 defines the group for all descriptors within this request See Table 18 Table 18 MOD_EXP_REQ Valid Descriptor opld Descriptor Value Function Description DPD_MM_LDCTX_EXP_ULCTX 0x5100 Perform a modular exponentiation operation 4 7 2 MOD SS EXP REQ COMMON REQ PREAMBLE nsigned long expBytes nsigned char expData nsigned long modBytes nsigned char modData nsigned long aDataBytes nsigned char aData nsigned long bDataBytes u u u u u u u unsigned char bData NUM_MM_SS_EXP_DESC defines the number of descriptors within the DPD MM SS EXP GROUP that use this request DPD_MM_SS_EXP_GROUP Ox5BO00 defines the group for all descriptors within this request See Table 19 Table 19 MOD_SS_EXP_REQ Valid Descriptor opld De
72. o the direct processing of data by the SEC core Process requests comprise the majority of the requests and all are executed using the same ioct1 access point In the section entitled Process Request Structures structures needed to compose these requests are described in detail Throughout the document the acronyms CHA crypto hardware accelerator and EU execution unit are used interchangeably Both acronyms indicate the device s functional block that performs the crypto functions requested The reader should understand that the design of this driver is a legacy holdover from two prior generations of security processors As applications have already been written for those processors certain aspects of the interface for this driver have been designed so as to maintain source level application portability with prior driver processor versions Where relevant in this document prior version compatibility features will be indicated to the reader Security Engine 2 x Reference Device Driver User s Guide Rev 1 2 Freescale Semiconductor Overview Table 2 contains acronyms and abbreviations that are used in this user s manual Table 2 Acronyms and Abbreviations Term Meaning AESA AES accelerator This term is synonymous with AESU in the Security Engine 2 x chapter of the PowerQUICC device reference manuals and other related documentation
73. on DPD 4 8 4 EC SPRBUILD ULCTX 0x5A00 Using separate values for a0 a3 and b0 b1 build a uniform data block that can be used to condense data to a point that allow it to be used with ECC operational requests ECC_PTADD_DBL_REQ FAMBLE COMMON REQ PR unsigned long modBytes unsigned char modData unsigned long buildDataBytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 29 Individual Request Type Descriptions nsig nsig nsig nsig nsig nsig nsig nsig nsig nsig Gy GG CAG SS Me Ge T OES ENG nsig 4 9 ned ned ned ned ned ned ned ned ned ned ned Cc i I Cc Cc ong har long nar long nar long nar long nar b2 b2 b3 b3 bl b2 b2 b2 b3 D3 har buildData DataBytes Data DataBytes Data DataBytes Data DataBytes Data DataBytes Data Table 27 ECC PTADD DBL REQ Valid Descriptor opld Descriptor Value Function Description DPD_EC_FPADD 0x5d00 Perform an FP add operation DPD_EC_FPDBL 0x5d01 Perform an FP double operation DPD_EC_F2MADD 0x5d02 Perform an F2M add operation DPD_EC_F2MDBL 0x5d03 Perform an F2M double operation IPSec Requests 4 9 1 IPSEC_CBC_REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes
74. ound IPSec encapsulated system payload packet _PAD_CMP using triple DES in CBC mode and MD5 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT_SHA 0x7512 Process an inbound IPSec encapsulated system payload packet _PAD_CMP using triple DES in CBC mode and SHA1 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 DPD_IPSEC_ESP_IN_TDES_ECB_DCRPT_SHA 0x7513 Process an inbound IPSec encapsulated system payload packet using single DES in CBC mode and SHA256 with auto padding If the packet signature does not match the expected signature and error will be returned Does not apply to SEC 2 0 4 10 802 11 Protocol Requests 4 10 COMMON_R ned 1 nsig nsig nsig nsig nsig nsig nsig nsig nsig nsig nsig Ca Ge GE Ge LE a GS E EC GG nsig 1 CCMP REQ RAMBLE ned 1 ned 1 ned 1 ned 1 ned 1 EQ PR ong ned char ong ned char ong ned char ong ned char ong ned char ong ned char keyBytes keyData ctxBytes context Frame AADBytes Frame AADData crypt crypt MICBytes MICData Data DataBytes DataBytes DataOut Security Engine 2 x Reference Device Driver User s Guide Rev 1 Fre
75. pId Descriptors Value Function Description DPD_SHA256_LDCTX_HMAC_ULCTX 0x4A00 Compute a SHA256 HMAC digest over a non padded message DPD_MD5_LDCTX_HMAC_ULCTX 0x4A01 Compute an MD5 HMAC digest over a non padded message DPD_SHA_LDCTX_HMAC_ULCTX 0x4A02 Compute a SHA1 HMAC digest over a non padded message DPD_SHA256_LDCTX_HMAC_PAD_ULCTX 0x4A03 Compute a SHA256 HMAC digest over a pre padded message DPD_MD5_LDCTX_HMAC_PAD_ULCTX 0x4A04 Compute an MD5 HMAC digest over a pre padded message DPD_SHA_LDCTX_HMAC_PAD_ULCTX 0x4A05 Compute a SHA1 HMAC digest over a pre padded message DPD SHA224 LDCTX HMAC ULCTX 0x40a6 Compute a SHA224 HMAC digest over a non padded message Does not apply to SEC 2 0 DPD SHA224 LDCTX HMAC PAD ULCTX 0x4a07 Compute a SHA224 HMAC digest over a pre padded message Does not apply to SEC 2 0 DPD_SHA256_LDCTX_HMAC_ULCTX_CMP 0x4a08 Compute a SHA256 HMAC digest over a non padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD_MD5_LDCTX_HMAC_ULCTX_CMP 0x4a09 Compute an MD5 HMAC digest over a non padded message Compare the resulting digest to an expected value and return an error if they do not compare Does not apply to SEC 2 0 DPD_SHA_LDCTX_HMAC_ULCTX_CMP 0x4a0a Compute a SHA1 HMAC digest over a non padded message Compar
76. r AO to B2 MUL1 operation DPD POLY LDCTX AO B2 MUL2 ULCTX 0x541D Perform a modular AO to B2 MUL2 operation DPD POLY LDCTX AO B2 ADD ULCTX Ox541E Perform a modular AO to B2ADD operation DPD POLY LDCTX_A1_B2 MUL1_ULCTX 0x541F Perform a modular A1 to B2 MUL1 operation DPD POLY LDCTX_A1_B2 MUL2_ULCTX 0x5420 Perform a modular A1 to B2 MUL2 operation DPD POLY LDCTX_A1_B2 ADD_ULCTX 0x5421 Perform a modular A1 to B2 ADD operation DPD POLY LDCTX A2 B2 MUL1 ULCTX 0x5422 Perform a modular A2 to B2 MUL1 operation DPD POLY LDCTX A2 B2 MUL2 ULCTX 0x5423 Perform a modular A2 to B2 MUL2 operation DPD POLY LDCTX A2 B2 ADD ULCTX 0x5424 Perform a modular A2 to B2 ADD operation DPD POLY LDCTX A3 B2 MUL1 ULCTX 0x5425 Perform a modular A3 to B2 MUL1 operation DPD POLY LDCTX A3 B2 MUL2 ULCTX 0x5426 Perform a modular A3 to B2 MUL2 operation DPD POLY LDCTX A3 B2 ADD ULCTX 0x5427 Perform a modular A3 to B2 ADD operation DPD POLY LDCTX AO B3 MUL1 ULCTX 0x5428 Perform a modular AO to B3 MUL1 operation DPD POLY LDCTX AO B3 MUL2 ULCTX 0x5429 Perform a modular AO to B3 MUL2 operation DPD POLY LDCTX AO B3 ADD ULCTX 0x542A Perform a modular AO to B3 ADD oper
77. r to input iv ipsecReg cryptKeyBytes 24 DES key length ipsecReg cryptKeyData EncKey pointer to DES key Security Engine 2 x Reference Device Driver User s Guide Rev 1 46 Freescale Semiconductor Linux Environment ipsecReq hashInDataBytes 8 length of data to be hashed only ipsecReq hashInData PlainText pointer to data to be hashed only ipsecReq inDataBytes packet_length 8 length of data to be hashed and encrypted ipsecReq inData amp PlainText 8 pointer to data to be hashed and encrypted ipsecReq cryptDataOut Result pointer to encrypted results ipsecReg hashDataOutBytes 20 length of output digest ipsecReg hashDataOut digest pointer to output digest ipsecReq nextReq 0 no chained requests call the driver status Ioctl device IOCTL PROC REQ amp ipsecReq First Level Error Checking if status 0 void notifyFunc void Second Level Error Checking if ipsecReq status 0 6 Linux Environment This section describes the driver s adaptation to and interaction with the Linux operating system as applied to PPC processors 6 1 Installation 6 1 1 Driver Source The SEC 2 x driver installs into Linux as a loadable module To build the driver as a module it must be installed into the kernel source tree to be included in the kernel build process The makefile i
78. rgical implant into the body or other applications intended to support or sustain life or for any other application in which the failure of the Freescale Semiconductor product could create a situation where personal injury or death may occur Should Buyer purchase or use Freescale Semiconductor products for any such unintended or unauthorized application Buyer shall indemnify and hold Freescale Semiconductor and its officers employees subsidiaries affiliates and distributors harmless against all claims costs damages and expenses and reasonable attorney fees arising out of directly or indirectly any claim of personal injury or death associated with such unintended or unauthorized use even if such claim alleges that Freescale Semiconductor was negligent regarding the design or manufacture of the part Freescale and the Freescale logo are trademarks of Freescale Semiconductor Inc All other product or service names are the property of their respective owners The Power Architecture and Power org word marks and the Power and Power org logos and related marks are trademarks and service marks licensed by Power org Freescale Semiconductor Inc 2005 2006 ey Z freescale semiconductor
79. ror and driver status unsigned long errorcode Error that the request generated void request Pointer to original request Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 11 User Interface STATUS REQ driverstatus Detailed information as to the state of the hardware and the driver at the time of an error 3 3 6 Process Request Structures All process request structures contain a copy of identical request header information which is defined by the COMMON_REQ_PREAMBLE macro The members of this header must be filled in as needed by the user prior to the issue of the user s request Descriptions of the process request structures are shown in Table 7 unsigned long unsigned char unsigned char unsigned char unsigned char opId scatterBufs notifyFlags reserved hannel PSEC2_NOTIFY_ROU PSEC2_NOTIFY_CTX PSEC2_NOTIFY_ON_1 SEC2_NOTIFY_ON_ERROR_CTX TIN otify NotifyCtx E ERROR_ROUTIN Gl txNotifyOnErr int void Process Request Structure g n P notify on error 6 status ED extReq Table 7 Process Request Structures Description opId operation Id which identifies what type of request this is It is normally associated with a specific type of cryptographic operation see Individual Requests for all supported request types scatterBufs A bit
80. rypting in AES using CBC mode with MD5 DPD_IPSEC_AES_CBC_DECRYPT_SHA 0x800A Perform the IPSec process of decrypting in AES using CBC mode with SHA 1 DPD_IPSEC_AES_CBC_DECRYPT_SHA256 0x800B Perform the IPSec process of decrypting in AES using CBC mode with SHA 256 4 9 4 IPSEC_AES ECB REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes unsigned char hashKeyData unsigned long cryptKeyBytes unsigned char cryptKeyData unsigned long hashInDataBytes unsigned char hashInData Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 33 Individual Request Type Descriptions unsigned long inDataBytes unsigned char inData unsigned char cryptDataOut unsigned long hashDataOutBytes unsigned char hashDataOut NUM IPSEC AES ECB DESC defines the number of descriptors within the DPD IPSEC AES ECB GROUP that use this request DPD IPSEC AES ECB GROUP 0x8100 defines the group for all descriptors vvithin this request See Table 31 Table 31 IPSEC AES ECB REQ Valid Descriptors opld Descriptors Value Function Description DPD IPSEC AES ECB ENCRYPT MD5 APAD 0x8100 Perform the IPSec process of encrypting in AES using ECB mode with MD5 auto padding DPD_IP
81. s Table 15 HASH_REQ Valid Descriptors 0x4500 opid continued DPD_SHA256_LDCTX_HASH_PAD_ULCTX_CMP 0x4508 Compute digest over pre padded data using a SHA 256 hash algorithm with an external context Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD_MD5_LDCTX_HASH_PAD_ULCTX_CMP 0x4509 Compute digest over pre padded data using an MD5 hash algorithm with an external context Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD_SHA_LDCTX_HASH_PAD_ULCTX_CMP 0x450a Compute digest over pre padded data using a SHA 1 hash algorithm with an external context Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD_SHA256_LDCTX_IDGS_HASH_PAD_ULCTX_CMP 0x450b Compute digest over pre padded data using SHA 256 with its standard initialization Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD_MD5_LDCTX_IDGS_HASH_PAD_ULCTX_CMP 0x450c Compute digest over pre padded data using MD5 with its standard initialization Compare resulting digest to external value and return an error if they do not match Does not apply to SEC 2 0 DPD_SHA_LDCTX_IDGS_HASH_PAD_ULCTX_CMP 0x450d Compute digest over pre padded data using SHA1 with its standard
82. s Guide Rev 1 Freescale Semiconductor 31 Individual Request Type Descriptions NUM IPSEC ECB DESC defines the number of descriptors within the DPD IPSEC ECB GROUP that use this request DPD IPSEC ECB GROUP 0x7100 defines the group for all descriptors within this request See Table 29 Table 29 IPSEC_ECB_REQ Valid Descriptors opld Descriptors Value Function Description DPD_IPSEC_ECB_SDES_ENCRYPT_MD5 0x7100 Perform the IPSec process of encrypting in single DES using ECB mode with MD5 padding DPD IPSEC ECB SDES ENCRYPT SHA 0x7101 Perform the IPSec process of encrypting in single DES using ECB mode with SHA 1 padding DPD_IPSEC_ECB_SDES_ENCRYPT_SHA256 0x7102 Perform the IPSec process of encrypting in single DES using ECB mode with SHA 256 padding DPD_IPSEC_ECB_SDES_DECRYPT_MD5 0x7103 Perform the IPSec process of decrypting in single DES using ECB mode with MD5 padding DPD IPSEC ECB SDES DECRYPT SHA 0x7104 Perform the IPSec process of decrypting in single DES using ECB mode with SHA 1 padding DPD IPSEC ECB SDES DECRYPT SHA256 0x7105 Perform the IPSec process of decrypting in single DES using ECB mode with SHA 256 padding DPD_IPSEC_ECB_TDES_ENCRYPT_MD5 0x7106 Perform the IPSec process of encrypting in triple DES using ECB mode with MD5 padding DPD_IPSEC_ECB_TDES_ENCRYPT_SHA 0x7107 Perform the IPSec
83. scriptor Value Function Description DPD_MM_SS_RSA_1 ta PR 0x5B00 Perform a single stage RSA exponentiation operation 4 7 3 MOD_R2MODN_REQ COMMON REQ PREAMBLE unsigned long modBytes unsigned char modData unsigned long outBytes unsigned char outData NUM_MM_R2MODN_DESC defines the number of descriptors within the DPD MM LDCTX R2MODN ULCTX GROUP that use this request Security Engine 2 x Reference Device Driver User s Guide Rev 1 24 Freescale Semiconductor Individual Request Type Descriptions DPD MM LDCTX R2MODN ULCTX GROUP 0x5200 defines the group for all descriptors within this request See Table 20 Table 20 MOD R2MODN REQ Valid Descriptor opld Descriptor Value Function Description DPD_MM_LDCTX_R2MODN_ULCTX 0x5200 Performa R2MOD operation upon a public key 4 7 4 MOD_RRMODP_REQ COMMON REQ PREAMBLE unsigned long nBytes nsigned long pBytes nsigned char pData u u unsigned long outBytes u nsigned char outData NUM_MM_RRMODP_DESC defines the number of descriptors within the DPD MM LDCTX RRMODP ULCTX GROUP that use this request DPD MM LDCTX RRMODP ULCTX GROUP 0x5300 defines the group for all descriptors within this request See Table 21 Table 21 MOD RRMODP REQ Valid Descriptor opld Descriptor Value Function Description DPD_MM_LDC
84. so because they are not in the user s context auxiliary handlers should never be used from a Linux user state application since the user state handler cannot be directly invoked 4 Individual Request Type Descriptions 4 1 Random Number Requests 4 1 1 RNG_REQ COMMON REQ PREAMBLE unsigned long rngBytes unsigned char rngData NUM_RNGA_DESC defines the number of descriptors within the DPD RNG GROUP that use this request DPD_RNG_GROUP 0x1000 defines the group for all descriptors within this request See Table 9 Table 9 RNG_REQ Valid Descriptor opId Descriptor Value Function Description DPD_RNG_GETRN 0x1000 Generate a series of random values 4 2 DES Requests 4 2 1 DES CBC CRYPT REQ COMMON REQ PREAMBLE unsigned long d inlvBytes 0 or 8 bytes unsigned char inIvData unsigned long keyBytes 8 16 or 24 bytes unsigned char keyData unsigned long inBytes multiple of 8 bytes unsigned char inData unsigned char outData output length input length unsigned long outIvBytes 0 or 8 bytes unsigned char outIvData Security Engine 2 x Reference Device Driver User s Guide Rev 1 16 Freescale Semiconductor this request NUM DES LOADC DPD DES CBC C1 X D Individual Request Type Descriptions ESC defines the number of descriptors within the DPD DES CBC CTX GROUP t
85. ta ong b2DataBytes char b2Data ong b30utDataBytes char b30utData EC POINT Di use this request ECC Public Rey Requests ESC defines the number of descriptors within the DPD EC_LDCTX_kP_ULCTX_GROUP that DPD_EC_LDCTX_kP_ULCTX_GROUP 0x5800 defines the group for all descriptors within this request Table 24 Table 24 ECC_POINT_REQ Valid Descriptors opld Descriptors Value Function Description DPD_EC_FP_AFF_PT_MULT 0x5800 Perform a PT MULT operation in an affine system DPD_EC_FP_PROJ_P UL 0x5801 Perform a PT MULT operation in a projective system DPD_EC_F2M_AFF_P UL 0x5802 Perform an F2M PT_MULT operation in an affine system DPD EC F2M PROJ PT MULT 0x5803 Perform an F2M PT MULT operation in a projective system DPD EC FP LDCTX ADD ULCTX 0x5804 Perform an FP add operation DPD_EC_FP_LDCTX_DOUBLE_ULCTX 0x5805 Perform an FP double operation DPD_EC_F2M_LDCTX_ADD_ULCTX 0x5806 Perform an F2M add operation DPD_EC_F2M_LDCTX_DOUBLE_ULCTX 0x5807 Perform an F2M double operation 4 8 2 ECC_20P_REQ COMMON_R unsigned unsigned unsigned unsigned unsigned EQ PREAMBLE ong bDataBytes char bData ong aDataBytes char aData ong modBytes Security Engine 2 x Reference Device Driver User s Guide Rev 1 28 Freescale Semiconductor unsigned c
86. tin ioct 1 Function IOCTL_PROC_REQ Primary form of making a request of the security engine Passes a pointer to a detailed request block specific to the type of request being made IOCTL_GET_STATUS Get detailed internal status after execution Passes pointer to a STATUS_REQ IOCTL_RESERVE_CHANNEL_S Reserve a channel for exclusive use by a task such that it will not be shared with other TATIC requestors Is passed a pointer to a channel argument see the channel element in GENERIC_REQ that will be updated with a channel number for use in subsequent requests to that channel IOCTL_RELEASE_CHANNEL Release a channel from exclusive use by a task Is passed a pointer to a channel same as for IOCTL_RESERVE_CHANNEL_STATIC IOCTL_MALLOC Allocate a contiguous block of kernel memory for use in the processing of a request Parameter is a pointer to the allocated block Note that this is only valid on systems that support privileged memory access IOCTL_FREE Free a block of memory originally allocated by TOCTL MALLOC Parameter is a pointer to the block to free IOCTL_COPYFROM Pointer to type MALLOC_REQ which will hold information about a user buffer that will be copied from user memory space to kernel memory space allocated by IOCTL_MALLOC IOCTL_COPYTO Pointer to type MALLOC_REQ which will hold information about a user buffer that will be copied from kernel memory space allocated by TOCTL MALLOC back to a user s buffer IOCTL_INSTALL_AUX_HA
87. vOutBytes unsigned char ivOutData unsigned char cmpData NUM_TLS_STREAM_OUTBOUND_DESC defines the number of descriptors within the DPD_TLS_STREAM_OUTBOUND_GROUP that use this request DPD_TLS_STREAM_OUTBOUND_GROUP 0x9300 defines the group for all descriptors within this request See Table 40 Table 40 TLS_STREAM_OUTBOUND_REQ Valid Descriptors opld Descriptors Value Function Description DPD_TLS_STREAM_OUTBOUND_MD5 0x9300 Prepare an outbound message using MD5 and an RC4 initial context DPD_TLS_STREAM_OUTBOUND_SHA1 0x9301 Prepare an outbound message using SHA1 and an RC4 initial context DPD_TLS_STREAM_OUTBOUND_SHA256 0x9302 Prepare an outbound message using SHA256 and an RC4 initial context DPD_TLS_STREAM_OUTBOUND_CTX_MD5 0x9303 Prepare an outbound message using MD5 and an RC4 external context DPD_TLS_STREAM_OUTBOUND_CTX_SHA1 0x9304 Prepare an outbound message using SHA1 and an RC4 external context DPD_TLS_STREAM_OUTBOUND_CTX_SHA256 0x9305 Prepare an outbound message using SHA256 and an RC4 external context 5 Sample Code The follovving sections provide sample codes for DES and IPSec the User Structure 5 1 DES Sample defin DES_LOADCTX_CRYPT_RI EQ desencReq Security Engine 2 x Reference Device Driver User s Guide Rev 1 Freescale Semiconductor 45 S A CE Sample Code fill the User Request structure with appropriate pointers desencReq opId DP
88. y Engine 2 x Reference Device Driver User s Guide Rev 1 12 Freescale Semiconductor User Interface Table 7 Process Request Structures continued ctxNotifyOnErr context area that is filled in by the driver when there is an error status will contain the returned status of request nextReq pointer to next request which allows for multiple request to be linked together and sent via a sin gle ioct 1 function call The additional data in the process request structures is specific to each request refer to the specific structure for this information 3 3 7 Scatter Gather Buffer Management A unique feature of the SEC 2 x core is the presence of the hardware s ability to read and act on a scatter gather description list for a data buffer This allows the hardware to more efficiently deal with buffers located in memory belonging to a non privileged process memory which may not be contiguous but instead may be at scattered locations determined by the memory management scheme of the host system Any data buffer in any request may be marked as a scattered memory buffer by the requestor as needed For the requestor to do so two actions must be taken e A linked list of structures of type EXT_SCATTER_ELEMENT One per memory fragment must be constructed to describe the whole of the buffer s content e The buffer pointer shall reference the head of this list not the data itself The buffers containing s
89. yData nsigned long ivBytes nsigned char ivData nsigned long cipherKeyBytes nsigned char cipherKeyData nsigned long hashOnlyBytes Gol Gy Ge Gy Ge FG IG Es nsigned long hashOnlyData Security Engine 2 x Reference Device Driver User s Guide Rev 1 42 Freescale Semiconductor unsigned long mainDataBytes unsigned long outBytes unsigned long outData unsigned long MACbytes unsigned long cipherOnlyBytes unsigned long cipherOnlyData unsigned long ivOutBytes unsigned long ivOutData NUM TLS BLOCR QUI DPD TLS BLOCR QUI DPD TLS BLOCR QUI Table 38 Individual Request Type Descriptions BOUND_DESC defines the number of descriptors within the BOUND_GROUP that use this request Table 38 TLS_BLOCK_OUTBOUND_REQ Valid Descriptors opld BOUND_GROUP 0x9100 defines the group for all descriptors within this request See Descriptors Value Function Description DPD_TLS_BLOCK_OUTBOUND_SDES_MD5 0x9100 Prepare an outbound message using single DES and MD5 DPD_TLS B OCR 1 OUTBOUND S DES SH Al 0x9101 Prepare an outbound message using single DES and SHA1 DPD_TLS B OCR 1 OUTBOUND_S DES_SH A256 0x9102 Prepare an outbound message using single DES and SHA256 DPD_TLS OCR 1 OUTBOUND DES_MD5 0x9103 Prepare an outbound message using triple DES and MD5 DPD_TLS

Security Engine 2.x Reference Device Driver User`s Guide: For

Contents

Download Pdf Manuals

Related Search

Related Contents