Home

Freescale Semiconductor SEC2SWUG User's Manual

1. Freescale Semiconductor Individual Request Type Descriptions 4 7 2 MOD SS EXP REQ COMMON REQ PREAMBLE unsigned long unsigned char unsigned long unsigned char unsigned long unsigned char unsigned long unsigned char expBytes texpData modBytes modData aDataBytes aData bDataBytes 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 0x5B00 defines the group for all descriptors within this request Descriptors DPD MM SS RSA EXP Table 16 MoD ss EXP REQ Valid Descriptor opId Value Function Description 0x5B00 Perform a single stage RSA exponentiation operation 4 7 3 MOD R2MODN REQ COMMON REQ PREAMBLE unsigned long unsigned char unsigned long unsigned char modBytes modData outBytes outData NUM_MM_R2MODN_DESC defines the number of descriptors within the DPD_MM_LDCTX_R2MODN_ULCTX_GROUP that use this request DPD_MM_LDCTX_R2 ODN_ULCTX_GROUP 0x5200 defines the group for all descriptors within this request Descriptor DPD MM LDCTX R2MODN ULCTX Table 17 MOD R2MODN REQ Valid Descriptor opld Value Function Description 0x5200 Perform a R2MOD operation upon a public key SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 21 Individual Request Type Descriptions 4 7
2. TX Al B2 MUL1 ULCTX Value 0x5400 0x5401 0x5402 0x5403 0x5404 0x5405 0x5406 0x5407 0x5408 0x5409 0x540A 0x540B 0x540C 0x540D 0x540E 0x540F 0x5410 0x5411 0x5412 0x5413 0x5414 0x5415 0x5416 0x5417 0x5418 0x5419 Ox541A 0x541B 0x541C 0x541D 0x541E 0x541F Function Description Perform a modular MUL1 operation Perform a modular MUL2 operation Perform a modular ADD operation Perform a modular SUB operation Perform a modular AO to BO MUL1 operation Perform a modular AO to BO MUL2 operation Perform a modular AO to BO ADD operation Perform a modular A1 to BO MUL1 operation Perform a modular A1 to BO MUL2 operation Perform a modular A1 to BO ADD operation Perform a modular A2 to BO MUL1 operation Perform a modular A2 to BO MUL2 operation Perform a modular A2 to BO ADD operation Perform a modular A3 to BO MUL1 operation Perform a modular A3 to BO MUL2 operation Perform a modular A3 to BO ADD operation Perform a modular AO to B1 MUL1 operation Perform a modular A to B MUL2 operation Perform a modular AO to B1 ADD operation Perform a modular A1 to B1 MUL1 operation Perform a modular A1 to B1 MUL2 operation Perform a modular A1 to B1 ADD operation Perform a modular A2 to B1 MUL1 operation Perform a modular A2 to B1 MUL2 operation Perform a modular A2 to B1 ADD operation Perform a modular A3 to B1 MUL1 operation Perform a modular A3 to B1 MUL2 operation Perform a modular A3 to B1 ADD operation
3. DPD MD5 LDCTX SHA 256 IDGS hash algorithm then store the resulting padded context DPD SHA LDCTX IDGS HASH PAD ULCTX 0x4504 Compute digest with pre padded data using an MD5 IDGS hash algorithm then store the resulting padded context IDGS HASH PAD ULCTX 0x4505 Compute digest with pre padded data using an 4 5 HMAC SHA 1 IDGS hash algorithm then store the resulting padded context Requests 4 5 1 HMAC_PAD_REQ COMMON REQ PREAMBLE unsigned long keyBytes unsigned char keyData unsigned long inBytes unsigned char inData unsigned long outBytes length is fixed by algorithm unsigned char outData NUM_HMAC_PAD_D use this request DPD HASH LDCTX ESC defines the number of descriptors within the DPD HASH LDCTX HMAC ULCTX GROUP that HMAC ULCTX GROUP Ox4A00 defines the group for all descriptors within this request SEC 2 0 Reference Device Driver User s Guide Rev 0 18 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Individual Request Type Descriptions Table 13 HMAC PAD REQ Valid Descriptors opId Descriptors Value DPD SHA256 LDCTX HMAC ULCTX 0x4A00 DPD MD5 LDCTX HMAC ULCTX Ox4A01 DPD SHA LDCTX HMAC ULCTX 0x4A02 DPD SHA256 LDCTX HMAC PAD ULCTX 0x4A03 DPD MD5 LDCTX HMAC PAD ULCTX 0x4A04 DPD SHA LDCTX HMAC PAD ULCTX Ox4A05 4 6 AES Requests 4 6 1 AESA_CRYPT_REQ COMMON REQ PREAMBLE unsigned long unsigned char unsigned l
4. 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 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 SEC2 device under kernel mode is relatively straightforward Once the driver module has loaded which will initialize the device direct calls to the ioct1 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 sui
5. Descriptors opId Descriptor Value Function Description DPD EC F2M LDCTX MUL1 ULCTX 0x5900 Perform an F2M MULT1 operation 4 8 3 ECC SPRBUILD REQ COMMON _ REQ PREAMBLE unsigned long a0DataBytes unsigned char a0Data unsigned long alDataBytes unsigned char alData unsigned long a2DataBytes unsigned char a2Data unsigned long a3DataBytes unsigned char a3Data unsigned long b0DataBytes unsigned char b0Data unsigned long bilDataBytes unsigned char b1Data unsigned long buildDataBytes unsigned char buildData NUM_EC_SPKBUILD_DESC defines the number of descriptors within the DPD_EC_SPKBUILD_GROUP that use this request DPD_EC_SPKBUILD_GROUP 0x5a00 defines the group for all descriptors within this request Table 22 ECC SPRBUILD REQ Valid Descriptor opId Descriptor Value Function Description DPD EC SPRBUILD ULCTX OXSA00 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 26 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor 4 8 4 ECC PTADD DBL REQ COMMON REQ PREAMBLE unsigned long modBytes unsigned char modData unsigned long buildDataBytes unsigned char buildData unsigned long b2DataBytes unsigned char b2Data unsigned long b3DataBytes unsigned char b3Data u
6. ENCRYPT SHA256 PAD DPD IPSEC ECB TDES DECRYPT MD5 PAD DPD_IPSEC ECB TDES DECRYPT SHA PAD DPD_IPSEC ECB TDES DECRYPT SHA256 PAD 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 unsigned long hashDataOutBytes unsigned char hashDataOut 0x7108 0x7109 0x710A 0x710B Perform the IPSec process of encrypting in triple DES using ECB mode with SHA 256 padding Perform the IPSec process of decrypting in triple DES using ECB mode with MD5 padding Perform the IPSec process of decrypting in triple DES using ECB mode with SHA 1 padding Perform the IPSec process of decrypting in triple DES using ECB mode with SHA 256 padding NUM_IPSEC_AES_CBC_DESC defines the number of descriptors within the DPD_IPSEC_AES_CBC_GROUP that use this request DPD_IPSEC_AES_CBC_GROUP 0x8000 defines the group for all descriptors within this request Table 26 IPSEC AES CBC REQ Valid Descriptors op Id Descriptors DPD IPSEC AES CBC ENCRYPT MD5 APAD DPD IPSEC AES CBC ENCRYPT SHA APAD Value 0x8000 0x8001 DPD IPSEC AES CBC ENCRYPT SHA256 APAD 0x8002 Function Descripti
7. 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 variable so that the developer can turn message sources on or off as required This global is named SEC2DebugLevel and contains an ORed combination of any of the following bits DBGTXT SETRQ Messages from request setup operations nevv 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 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 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 section Note that the user may wish to reorganize header file locations consistent with the file location conventions appropriate for their system configuration Header Description Sec2 h Primary public header file for all users of the driver Sec2Driver h Driver Hardware interfaces private to the driver itself
8. PAD IPSEC ESP OUT TDES CBC CRPT SHA PAD IPSEC ESP OUT TDES CBC CRPT SHA256 IPSEC ESP IN TDES CBC DCRPT MD5 PAD IPSEC ESP IN TDES CBC DCRPT SHA PAD IPSEC ESP IN TDES CBC DCRPT SHA256 IPSEC ESP OUT TDES ECB CRPT MD5 PAD IPSEC ESP OUT TDES ECB CRPT SHA PAD IPSEC ESP OUT TDES ECB CRPT SHA256 IPSEC ESP IN TDES ECB DCRPT MD5 PAD IPSEC ESP IN TDES ECB DCRPT SHA PAD IPSEC ESP IN TDES ECB DCRPT SHA256 Value 0x750A 0x750B 0x750C 0x750D 0x750E 0x750F 0x7510 0x7511 0x7512 0x7513 0x7514 0x7515 0x7516 0x7517 Function Description Process an inbound IPSec encapsulated system payload packet using single DES in CBC mode and SHA1 with auto padding Process an inbound IPSec encapsulated system payload packet using single DES in CBC mode and SHA256 with auto padding Process an outbound IPSec encapsulated system payload packet using triple DES in CBC mode and MD5 with auto padding Process an outbound IPSec encapsulated system payload packet using triple DES in CBC mode and SHA1 with auto padding Process an outbound IPSec encapsulated system payload packet using triple DES in CBC mode and SHA256 with auto padding Process an inbound IPSec encapsulated system payload packet using triple DES in CBC mode and MD5 with auto padding Process an inbound
9. Perform a modular AO to B2 MUL1 operation Perform a modular AO to B2 MUL2 operation Perform a modular AO to B2ADD operation Perform a modular A1 to B2 MUL1 operation SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 23 Individual Request Type Descriptions Table 19 MoD 20P REQ Valid Descriptors opId continued Descriptors Value Function Description DPD POLY LDCTX Al B2 MUL2 ULCTX 0x5420 Perform a modular A1 to B2 MUL2 operation DPD POLY LDCTX Al 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 n A0 to B3 MUL2 operation DPD POLY LDCTX AO B3 ADD ULCTX 0x542A Perform a modular AO to B3 ADD operation DPD POLY LDCTX Al B3 MUL1 ULCTX 0x542B Perform a modular A1 to B3 MUL1
10. SHA 0x800A Perform the IPSec process of decrypting in AES using CBC mode with SHA 1 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 unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned char char char char char char long long long long long hashKeyBytes hashKeyData cryptReyBytes cryptKeyData hashInDataBytes hashInData inDataBytes inData oryptDataout hashDataOutBytes hashDataOut NUM IPSEC AES ECB DESC defines the number of descriptors within the DPD IPSEC AES ECB GROUP that use this request DPD_IPSEC ECB_GROUP 0x8100 defines the group for all descriptors within this request SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 31 Individual Request Type Descriptions Table 27 IPSEC AES ECB REQ Valid Descriptors opId 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 IPSEC 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 Perfor
11. available at the time the OxEOO4FFFA request was being processed SEC2 INVALID LENGTH Length of requested data item is incompatible with OxEOO4FFF9 request type or data alignment incompatible SEC2 OUTPUT BUFFER ALIGNMENT Output buffer alignment incompatible with request OXE004FFF8 type SEC2 ADDRESS PROBLEM Driver could not translate argued address into a OXE004FFF6 physical address SEC2 INSUFFICIENT REQS Request entry pool exhausted at the time of request OXE004FFF5 processing try again later SEC2 CHA ERROR CHA flagged an error during processing check the OxEOO4FFF2 error notification context if one was provided to the request SEC2 NULL REQUEST Request pointer was argued NULL OXE004FFF 1 SEC2 REQUEST TIMED OUT Timeout in request processing OXE004FFFO SEC2 MALLOC FAILED Direct kernel memory buffer request failed OxEOO4FFEF 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 is OXEO04FFEA full SEC2 FETCH FIFO OVERFLOW Too many DPD s written to a channel indicates an OXE004FFE9 internal driver problem SEC2 BUS MASTER ERROR Processor could not acquire the bus for a data OXE004FFE8 transfer SEC2 SCATTER LIST ERROR Caller s list describing a scatter gather buf
12. 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 scatter 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 It contains these elements void next pointer to next fragment in list NULL if at end of list void tfragment pointer to contiguous data fragment unsigned short size size of this fragment in bytes With this the caller must construct the list of all the fragments need
13. be a process ID if a user state signal handler will flag completion Refer back to notifyFlags for more info pointer to context area to be passed back through the notification routine SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 11 User Interface notify on error pointer to the notify on error routine that will be called when the request has completed unsuccessfully May instead be a process ID if a user state signal handler will flag completion Refer back to not i fyF lags for more info 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 single i oct 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 0 processor is 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
14. by the device in question The third argument is the pointer to the SEC2 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 opID The operation ID is used by the device driver to determine the format of the request structure e While all requests have a channel member it s presence is a holdover from earlier variations of the security engine For SEC2 it no longer has a valid use and is retained solely to maintaining request compatibility for applications written for older security engines 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 operation as indicated by the interrupt The valid values for this status member are DONE normal status or ERROR error status e All process request structures have two notify members notifyand 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 caller s operational requirements e All process request structures have a next request member This allows the application to chain multiple process re
15. ipsec ipsec ipsec Req Req Req Req Req dynamic descriptor triple DES with SHA 1 authentication opId DPD IPSEC CBC TDES ENCRYPT SHA PAD channel 0 notify void notifyFunc notify on error void notifyFunc status 0 SEC 2 0 Reference Device Driver User s Guide Rev 0 Sample Code Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 37 Sample Code ipsecReq hashKeyBytes 16 key length for HMAC SHA 1 ipsecReq hashKeyData authKey pointer to HMAC Key ipsecReq cryptCtxInBytes 8 length of input iv ipsecReq cryptCtxInData in_iv pointer to input iv ipsecReq cryptKeyBytes 24 DES key length ipsecReq cryptKeyData EncKey pointer to DES key 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 ipsecReq hashDataOutBytes 20 length of output digest ipsecReq 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 Checkin
16. operation DPD POLY LDCTX Al B3 MUL2 ULCTX 0x542C Perform a modular A1 to B3 MUL2 operation DPD POLY LDCTX Al 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 4 8 ECC Public Key Requests 4 8 1 ECC POINT REQ COMMON REQ PREAMBLE unsigned long nDataBytes unsigned char nData unsigned long eDataBytes unsigned char eData unsigned long buildDataBytes unsigned char buildData unsigned long bi1DataBytes SEC 2 0 Reference Device Driver User s Guide Rev 0 24 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor unsigned unsigned unsigned unsigned unsigned NUM EC POINT DI char long char long char this request b1Data b2DataBytes b2Data b30utDataBytes b30utData Individual Request Type Descriptions ESC defines the number of descriptors within the DPD_EC_LDCTX_kP_ULCTX_GROUP that use DPD_EC_LDCTX_kP_ULCTX_GROUP 0x5800 defines the group for all descr
17. the console stating that loading a module with a proprietary license will taint the kernel This message is normal expected and will not cause any adverse operation of your running system 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 in SEC 2 0 Reference Device Driver User s Guide Rev 0 40 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Porting 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 Interface Modules Throughout the remainder of the installation instructions the variables provided below are used Table 31 VxWorks Interface Module Variables Variable Definition CpuFamily Specifies the target CPU family such as PPC85XX ToolChain Specifies the tools such as gnu SecurityProcessor Specifies the target security processor should be SEC2 for this driver The following steps are used to build drivers and or the driver test and exercise code 1 Go to the command prompt or
18. unsigned long inDataBytes unsigned char inData SEC 2 0 Reference Device Driver User s Guide Rev 0 32 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Individual Request Type Descriptions 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 Table 28 IPSEC ESP REQ Valid Descriptors op1d Descriptors Value Function Description DPD IPSEC ESP OUT SDES ECB CRPT MD5 PAD 0x7500 Process an outbound IPSec encapsulated system payload packet using single DES in ECB mode and MD5 with auto padding DPD IPSEC ESP OUT SDES ECB CRPT SHA PAD 0x7501 Process an outbound IPSec encapsulated system payload packet using single DES in ECB mode and SHA1 with auto padding DPD IPSEC ESP OUT SDES ECB CRPT SHA256 0x7502 Process an outbound IPSec encapsulated system PAD payload packet using single DES in ECB mode and SHA256 with auto padding DPD IPSEC ESP IN SDES ECB DCRPT MD5 PAD 0x7503 Process an inbound IPSec encapsulated system payload packet using single DES in ECB mode and MD5 with auto padding DPD IPSEC ESP IN SDES ECB DCRPT SHA PAD 0x7504 Process an inbound IPSec enc
19. 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Device Driver Components Table 1 Acronyms and Abbreviations continued Term Meaning RDR 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 systems provided by VxWorks Company 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 Driver Initialization and Setup Application Request Processing Interrupt Service Routine 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 End User Application Driver Invoked Prepare Request Driver Code Non Blocking ioctl e Tracks Requests e Queue Request when Channels are Unavailable e Prepare Descriptors Driver e Start the descriptors execution in a channel Returns Callback Function Operation Starts ProcessingComplete Task Sleeps on Queue SEC2 x Execution Operation Completed Interrupt Generated Completes the User Request IsrMsgQId Execute Callb
20. 4 MOD RRMODP REQ COMMON REQ PREAMBLE unsigned long nBy unsigned long pBy unsigned char pDa tes tes ta unsigned long outBytes unsigned char out Data 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 Descriptor Table 18 MOD RRMODP REQ Valid Descriptor opId Value Function Description DPD MM LDCTX RRMODP ULCTX 0x5300 Compute the result of an RRMODP operation 4 7 5 MOD 2OP REQ unsigned long bDa unsigned char bDa unsigned long aDa unsigned char aDa taBytes ta taBytes ta unsigned long modBytes unsigned char mod Data unsigned long outBytes unsigned char out Data 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 22 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Descriptors DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP DP Individual Request Type Descriptions Table 19 MoD 20P REQ Val
21. CB mode Decrypt data in single DES using ECB mode Encrypt data in triple DES using ECB mode Decrypt data in triple DES using ECB mode SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 15 Individual Request Type Descriptions unsigned char tinCtxData unsigned long inBytes unsigned char inData unsigned char outData output length input length unsigned long outCtxBytes 257 bytes unsigned char outCtxData NUM_RC4_LOADCTX_UNLOADCTX_DESC defines the number of descriptors within the DPD_RC4_LDCTX_CRYPT_ULCTX_GROUP that use this request DPD_RC4_LDCTX_CRYPT_ULCTX_GROUP 0x3400 defines the group for all descriptors within this request Table 9 ARC4 LOADCTX CRYPT REQ Valid Descriptor opld Descriptor Value Function Description DPD RC4 LDCTX CRYPT ULCTX 0x3400 Load context encrypt using RC4 and store the resulting context 4 3 2 ARC4_LOADKEY_CRYPT_UNLOADCTX_REQ COMMON _ REQ PREAMBLE unsigned long keyBytes unsigned char keyData unsigned long inBytes unsigned char inData unsigned char outData output length input length unsigned long outCtxBytes 257 bytes unsigned char outCtxData NUM_RC4_LOADKEY_UNLOADCTX_DESC defines the number of descriptors within the DPD_RC4_LDKEY_CRYPT_ULCTX_GROUP that use this request DPD
22. 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 800 441 2447 303 675 2140 Fax 303 675 2150 LDCForFreescaleSemiconductor E hibbertgroup com 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
23. Freescale Semiconductor SEC2SWUG Rev 0 02 2005 SEC 2 0 Reference Device Driver User s Guide 1 Overview The SEC2 device driver manages the operation of the SEC 2 0 commonly instantiated into PowerQUICC processors It is a fully functional component meant to serve as an example of application interaction with the SEC2 core The driver is coded in ANSIC 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 Section 8 Porting addresses them Testing has been accomplished on VxWorks 5 5 and LinuxPPC using kernel version 2 4 27 Application interfaces to this driver are implemented through the ioctl 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 to the direct processing of data by the SEC2 core Process requests comprise the majority of the requests and all are executed using the same ioct 1 access point Structures needed to compose these requests are described in detail in Section 3 3 6 Process Request Structures Throughout the document the acronyms CHA crypto hardware accelerator and EU execution unit are used interchangeably This document contains information on a new product Specifications and information her
24. 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 surgical 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 The PowerPC name is a trademark of IBM Corp and is used under license All other product or service names are the property of their respective owners Freescale Semiconductor Inc 2005 SEC2SWUG Rev 0 02 2005 o o oe 2 freescale semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE
25. IPSec encapsulated system payload packet using triple DES in CBC mode and SHA1 with auto padding Process an inbound IPSec encapsulated system payload packet using triple DES in CBC mode and SHA256 with auto padding Process an outbound IPSec encapsulated system payload packet using triple DES in ECB mode and MD5 with auto padding Process an outbound IPSec encapsulated system payload packet using triple DES in ECB mode and SHA1 with auto padding Process an outbound IPSec encapsulated system payload packet using triple DES in ECB mode and SHA256 with auto padding Process an inbound IPSec encapsulated system payload packet using triple DES in ECB mode and MD5 with auto padding Process an inbound IPSec encapsulated system payload packet using triple DES in ECB mode and SHA1 with auto padding Process an inbound IPSec encapsulated system payload packet using triple DES in ECB mode and SHA256 with auto padding SEC 2 0 Reference Device Driver User s Guide Rev 0 34 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Individual Request Type Descriptions 4 10 802 11 Protocol Requests 4 10 1 CCMP REQ COMMON REQ PREAMBLE unsigned long keyBytes unsigned char keyData unsigned long ctxBytes unsigned char context unsigned long FrameDataBytes unsigned char FrameData unsigned long AADBytes unsigned char AADData unsigned long cryptDataBytes unsigned char cryptDataOut unsigne
26. 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 41 Porting 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 e Sec2Driver h 0 see2Initye hi 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 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 __vpa Translate a logical address to a physical address for hardware DMA if both are equivalent does nothing 8 2 C Source Files 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
27. NCI IPSEC ECB SDES ENCI IPSEC ECB SDES ENC IPSEC ECB SDES DEC IPSEC ECB SDES DEC IPSEC ECB SDES DEC IPSEC ECB TDES ENC IPSEC ECB TDES ENC RYPT_MD5_PAD RYPT_SHA PAD RYPT SHA256 PAD RYPT MD5 PAD RYPT SHA PAD RYPT SHA256 PAD RYPT MD5 PAD RYPT SHA PAD Value 0x7100 0x7101 0x7102 0x7103 0x7104 0x7105 0x7106 0x7107 Function Description Perform the IPSec process of encrypting in single DES using ECB mode with MD5 padding Perform the IPSec process of encrypting in single DES using ECB mode with SHA 1 padding Perform the IPSec process of encrypting in single DES using ECB mode with SHA 256 padding Perform the IPSec process of decrypting in single DES using ECB mode with MD5 padding Perform the IPSec process of decrypting in single DES using ECB mode with SHA 1 padding Perform the IPSec process of decrypting in single DES using ECB mode with SHA 256 padding Perform the IPSec process of encrypting in triple DES using ECB mode with MD5 padding Perform the IPSec process of encrypting in triple DES using ECB mode with SHA 1 padding SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 29 Individual Request Type Descriptions Table 25 IPSEC ECB REQ Valid Descriptors opId continued DPD_IPSEC ECB TDES
28. NGE WITHOUT NOTICE Freescale Semiconductor User Interface 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 3 User Interface 3 1 Application Interface In order to make a request of the SEC2 device the calling application populates a request structure with information describing the request 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 ioct1 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 argument is defined as the I O control code This code will specify the driver specific operation to be performed
29. RYPT 0x6001 DPD AESA CBC DECRYPT CRYPT RDR 0x6002 DPD AESA ECB ENCRYPT CRYPT 0x6003 DPD AESA ECB DECRYPT CRYPT 0x6004 DPD AESA ECB DECRYPT CRYPT RDR 0x6005 DPD AESA CTR CRYPT 0x6006 DPD AESA CTR HMAC 0x6007 4 7 Integer Public Key Requests 4 7 1 MOD_EXP_REQ COMMON REQ PREAMBLE unsigned long unsigned char unsigned long unsigned char unsigned long unsigned char unsigned long unsigned char aDataBytes aData expBytes texpData modBytes modData outBytes outData NUM MM EXP D this request DPD MM LDCTX Descriptors DPD MM LDCTX EXP ULCTX Function Description Perform encryption in AESA using CBC mode Perform decryption in AESA using CBC mode Perform decryption in AESA using CBC mode vvith RDR Perform encryption in AESA using ECB mode Perform decryption in AESA using ECB mode Perform decryption in AESA using ECB mode with RDK Perform CTR in AESA Perform AES CTR mode cipher operation with integrated authentication as part of the operation ESC defines the number of descriptors within the DPD_MM_LDCTX_EXP_ULCTX_GROUP that use EXP_ULCTX_GROUP 0x5100 defines the group for all descriptors within this request Table 15 MOD EXP REQ Valid Descriptor op1d Value 0x5100 Function Description Perform a modular exponentiation operation SEC 2 0 Reference Device Driver User s Guide Rev 0 20 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE
30. SEC2_MALLOC Pointer to be assigned to a block of kernel memory for holding caller data to be operated upon SEC2_FREE Pointer to free a block originally allocated by SEC2_MALLOC SEC2_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 SEC2_ MALLOC SEC2_COPYTO Pointer to type MALLOC_REQ which will hold information about a user buffer that will be copied from kernel memory space allocated by SEC2_MAlLLOC back to a user s buffer 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 7 User Interface Table 3 Channel Defines Define Description NUM AFHAS Number of ARC4 CHAs NUM DESAS Number of DES CHAs NUM MDHAS Number of MD CHAs NUM RNGAS Number of RNG CHAs NUM PRHAS Number of PR CHAs NUM AESAS Number of AESA CHAs 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 defined 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
31. 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 43 How to Reach Us Home Page www freescale com email support 8 freescale com USA Europe or Locations Not Listed Freescale Semiconductor Technical Information Center CH370 1300 N Alma School Road Chandler Arizona 85224 800 521 6274 480 768 2130 support 8 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 8 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 2666 8080 support japan freescale com Asia Pacific Freescale Semiconductor Hong Kong Ltd Technical Information
32. _RC4_LDKEY_CRYPT_ULCTX_GROUP 0x3500 defines the group for all descriptors within this request Table 10 ARC4 LOADREY CRYPT UNLOADCTX REQ Valid Descriptor opld Descriptor Value Function Description DPD RC4 LDKEY CRYPT ULCTX 0x3500 Load the cipher key encrypt using RC4 then save the resulting context SEC 2 0 Reference Device Driver User s Guide Rev 0 16 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor 4 4 Hash Requests 4 4 1 HASH REQ COMMON REQ PREAMBLE unsigned long unsigned char unsigned long unsigned char unsigned long unsigned char ctxBytes ctxData inBytes inData Individual Request Type Descriptions outBytes length is fixed by algorithm outData NUM_MDHA_DESC defines the number of descriptors within the DPD_HASH_LDCTX_HASH_ULCTX_GROUP that use this request DPD_HASH_LDCTX_HASH_ULCTX_GROUP 0x4400 defines the group for all descriptors within this request Table 11 HASH REQ Valid Descriptors 0x4400 opid Descriptors Value DPD SHA256 LDCTX HASH ULCTX 0x4400 DPD MD5 LDCTX HASH ULCTX 0x4401 DPD SHA LDCTX HASH ULCTX 0x4402 DPD SHA256 LDCTX IDGS HASH ULCTX 0x4403 DPD MD5 LDCTX IDGS HASH ULCTX 0x4404 DPD SHA LDCTX IDGS HASH ULCTX 0x4405 Function Description Load context compute digest using SHA 256 hash algorithm then save the resulting context Load context compute digest using MD5 hash algorithm then s
33. ack Function Writing a Message to the Queue Wakes the ProcessingComplete Task If no callback function is defined no callback takes place SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 3 Device Driver Components 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 IOBaseAddress e Initialize the security engine s registers Controller registers Channel registers 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 24 requests The driver will reject requests with an error when the queue is full e ProcessingComplete is spawned then pends on the IsrMsgQId which serves as the interface between the interrupt service routine and this deferred task 2 1 2 Request Dispatch Routine The request di
34. also contains references to register unregister the driver as a kernel module and to manage it s usage link count 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 IOConnect 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 42 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Porting 8 4 Conditional Compilation See the maRefile for specifics on the default build of the driver 8 5 Debug Messaging The driver includes a DBG define that allows for debug message output to the developer s console
35. apsulated system payload packet using single DES in ECB mode and SHA1 with auto padding DPD _ IPSEC ESP IN SDES ECB DCRPT SHA256 0x7505 Process an inbound IPSec encapsulated system PAD payload packet using single DES in ECB mode and SHA256 with auto padding DPD IPSEC ESP OUT SDES CBC CRPT MD5 PAD 0x7506 Process an outbound IPSec encapsulated system payload packet using single DES in CBC mode and MD5 with auto padding DPD IPSEC ESP OUT SDES CBC CRPT SHA PAD 0x7507 Process an outbound IPSec encapsulated system payload packet using single DES in CBC mode and SHA1 with auto padding DPD IPSEC ESP OUT SDES CBC CRPT SHA256 0x7508 Process an outbound IPSec encapsulated system PAD payload packet using single DES in CBC mode and SHA256 with auto padding DPD IPSEC ESP IN SDES CBC DCRPT MD5 PAD 0x7509 Process an inbound IPSec encapsulated system payload packet using single DES in CBC mode and MD5 with auto padding SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 33 Individual Request Type Descriptions Descriptors DPD DPD PAD DPD DPD DPD PAD DPD DPD DPD PAD DPD DPD DPD PAD DPD DPD DPD PAD IPSEC ESP Table 28 IPSEC ESP REQ Valid Descriptors opId continued IN SDES CBC DCRPT SHA PAD IPSEC ESP IN SDES CBC DCRPT SHA256_ IPSEC ESP OUT TDES CBC CRPT MD5
36. ave the resulting context Load context compute using SHA 1 hash algorithm then save the resulting context Load context compute digest with SHA 256 IDGS hash algorithm then store the resulting context Load context compute digest with MD5 IDGS hash algorithm then store the resulting context Load context compute digest with SHA 1 IDGS hash algorithm then store the resulting context NUM_MDHA_PAD_DESC defines the number of descriptors within the X_GROUP that use this request DPD HASH LDC1 rX HASH PAD UI LCT DPD HASH LDC1 rX HASH PAD UI LCT IX GROUP 0x4500 defines the group for all descriptors within this request SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 17 Individual Request Type Descriptions Table 12 HASH REQ Valid Descriptors 0x4500 op1d Descriptors Value Function Description DPD SHA256 LDCTX HASH PAD ULCTX 0x4500 Compute digest with pre padded data using an SHA 256 hash algorithm then store the resulting context DPD MD5 LDCTX HASH PAD ULCTX 0x4501 Compute digest with pre padded data using an MD5 DPD SHA LDCTX hash algorithm then store the resulting context HASH PAD ULCTX 0x4502 Compute digest with pre padded data using an SHA 1 hash algorithm then store the resulting context DPD SHA256 LDCTX IDGS HASH PAD ULCTX 0x4503 Compute digest with pre padded data using an
37. criptors opId Descriptors SDES ENC DPD IPSEC CBC SDES ENC DPD IPSEC CBC SDES ENC DPD IPSEC CBC SDES DEC DPD IPSEC CBC SDES DEC DPD IPSEC CBC SDES DEC DPD IPSEC CBC TDES ENCI DPD IPSEC CBC TDES ENC DPD IPSEC CBC TDES ENCI DPD IPSEC CBC TDES DEC DPD IPSEC CBC TDES DEC DPD IPSEC CBC TDES DEC RYPT_MD5_PAD RYPT_SHA PAD RYPT SHA256 PAD RYPT MD5 PAD RYPT SHA PAD RYPT SHA256 PAD RYPT MD5 PAD RYPT SHA PAD RYPT SHA256 PAD RYPT MD5 PAD RYPT SHA PAD RYPT SHA256 PAD Value 0x7000 0x7001 0x7002 0x7003 0x7004 0x7005 0x7006 0x7007 0x7008 0x7009 0x700A 0x700B Function Description Perform the IPSec process of encrypting in single DES using CBC mode with MD5 padding Perform the IPSec process of encrypting in single DES using CBC mode with SHA 1 padding Perform the IPSec process of encrypting in single DES using CBC mode with SHA 256 padding Perform the IPSec process of decrypting in single DES using CBC mode with MD5 padding Perform the IPSec process of decrypting in single DES using CBC mode with SHA 1 padding Perform the IPSec process of decrypting in single DES using CBC mode with SHA 256 padding Perform the IPSec process of encrypting in triple DES using CBC mode with MD5 pad
38. d long MICBytes unsigned char MICData 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 Table 29 CCMP_REQ Valid Descriptors opId Descriptors Value Function Description DPD 802 11 CCMP OUTBOUND 0x6500 Process an outbound CCMP packet DPD 802 11 CCMP INBOUND 0x8101 Process an inbound CCMP packet 4 11 SRTP Protocol Requests 4 11 1 SRTP_REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes unsigned char hashKeyData unsigned long keyBytes unsigned char keyData SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 35 Sample Code unsigned long ivBytes unsigned char ivData unsigned long HeaderBytes unsigned long inBytes unsigned char inData unsigned long ROCBytes unsigned long cryptDataBytes unsigned char cryptDataOut unsigned long digestBytes unsigned char digestData unsigned long outIvBytes unsigned char outIvData NUM_SRTP_DESC defines the number of descriptors within the DPD_SRTP_GROUP that use this request DPD_SRTP_GROUP 0x8500 defines the group for all descriptors within this request Table 30 SRTP_REQ Valid Descriptors opld Descriptors Value Function Description DPD_SRTP_OUTBOUND 0x8500 Process an outbound SRTP packet DPD_SRTP_INBOUND 0x8501 Pr
39. ding Perform the IPSec process of encrypting in triple DES using CBC mode with SHA 1 padding Perform the IPSec process of encrypting in triple DES using CBC mode with SHA 256 padding Perform the IPSec process of decrypting in triple DES using CBC mode with MD5 padding Perform the IPSec process of decrypting in triple DES using CBC mode with SHA 1 padding Perform the IPSec process of decrypting in triple DES using CBC mode with SHA 256 padding SEC 2 0 Reference Device Driver User s Guide Rev 0 28 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor 4 9 2 COMMON REQ PREAMBLE unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned NUM IPSEC request DPD IPSEC char char char char char char long long long long inDa inDa hash hash cryp ECB D Descriptors DPD DPD DPD DPD DPD DPD DPD DPD IPSEC ECB ECB G SDES ta IPSEC _ ECB REQ long hashKeyBytes hashKeyData cryptKeyBytes cryptKeyData hashInDataBytes hashInData taBytes DataOutBytes DataOut tDataOut Individual Request Type Descriptions ESC defines the number of descriptors within the DPD IPSEC ECB GROUP that use this ROUP 0x7100 defines the group for all descriptors within this request Table 25 IPSEC_ECB REQ Valid Descriptors op1d E
40. ed unsigned unsigned unsigned unsigned long long long long long long long long long long long long long long long long SEC2_STATUS through a typedef ChaAssignmentStatusRegister 2 InterruptControlRegister 2 InterruptStatusRegister 2 IdRegister ChannelStatusRegister NUM CHANNELS 2 ChannelConfigurationRegister NUM CHANNELS 2 CHAInterruptStatusRegister NUM CHAS 2 QueueEntryDepth FreeChannels FreeAfhas FreeDesas FreeMdhas FreePkhas FreeAesas FreeKeas BlockSize 3 3 5 2 SEC2 NOTIFY ON ERROR CTX Structure Structure returned to the notify_on_error callback routine that was setup in the initial process request This structure contains the original request structure as well as an error and driver status unsigned long errorcode Error that the request generated void request Pointer to original request SEC 2 0 Reference Device Driver User s Guide Rev 0 10 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor 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 the a copy of the same 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 is
41. ed 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 completion 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 12 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor User Interface 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 MarkScatterBuffer 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 opId element mus
42. ein are subject to change without notice Freescale Semiconductor Inc 2005 All rights reserved SO A EN De RE SS EP Contents OVERVIEW ico 28a lec oa dota el ge Met 1 Device Driver Components 3 User Interface Li ies redactar esa eaaa 5 Individual Request Type Descriptions 14 Sample COM iiss seis at s gem wr pesa ec pl aa ea al 36 Linux Environment eu LL 39 VxWorks Environment u e Le 40 POTS esa Genis des suet senna nes Do dRagaearas 41 ey oe PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Z freescale semiconductor Overview Both acronyms indicate the device s functional block that performs the crypto functions requested For further details on the device see the Hardware Reference Manual 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 Table 1 contains acronyms and abbreviations that are used in this user s guide Table 1 Acronyms and Abbreviations Term Meaning AESA AES accele
43. fer is OXEO04FFE7 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 SEC2 IO VXWORKS DRIVER TABLE Error due to VxWorks not being able to add driver to 1003 ADD ERROR table SEC2 IO INTERRUPT ALLOCATE ER Error due to interrupt allocation error 1004 ROR SEC2 VXWORKS CANNOT CREATE QU Error due to VxWorks not being able to create the ISR 1009 EUE queue in TOTnitQs SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 9 User Interface Table 5 Callback Error Status Return Code continued Define Description Value 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 3 3 5 1 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 unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsign
44. ference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 13 Individual Request Type Descriptions 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 Table 6 RNG_REQ Valid Descriptor op1d 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 inIvBytes 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 NUM_DES_LOADCTX_DESC defines the number of descriptors within the DPD_DES_CBC_CTX_GROUP that use this request DPD_DES_CBC_CTX_GROUP 0x2500 defines the group for all descriptors within this request SEC 2 0 Reference Device Driver User s Guide Rev 0 14 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Individual Request Type Descr
45. g if status 0 void notifyFunc void Second Level Error Checking if ipsecReq status 0 SEC 2 0 Reference Device Driver User s Guide Rev 0 38 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor Linux Environment 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 SEC2 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 included 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 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 T 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 ioct 1 Thus the system will need a device file created to assign a name to the device
46. id Descriptors opId MM LDCTX MUL1 ULCTX MM LDCTX MUL2 ULCTX MM LDCTX ADD ULCTX MM LDCTX SUB ULCTX POLY L DCT X AO BO MUL1 ULCTX POLY L DCT TX AO BO MUL2 ULCTX POLY L DCT TX AO BO ADD_ULCTX POLY DCT TX Al BO MUL1 ULCTX POLY DCT TX Al BO MUL2 ULCTX POLY DCT X Al BO ADD_ULCTX POLY DCT X A2 BO MUL1 ULCTX POLY DCT TX A2 BO MUL2 ULCTX POLY DCT TX A2 BO ADD_ULCTX POLY DCT TX A3 BO MUL1 ULCTX POLY DCT TX A3 BO MUL2 ULCTX POLY DCT TX A3 BO ADD_ULCTX POLY DCT X AO B1 MUL1 ULCTX POLY DCT TX AO Bl MUL2 ULCTX POLY DCT TX AO B1 ADD_ULCTX POLY DCT TX Al Bl MUL1 ULCTX POLY DCT TX Al B1 MUL2 ULCTX POLY DCT TX Al Bl ADD_ULCTX POLY DCT TX A2 Bl MUL1 ULCTX POLY DCT TX A2 Bl MUL2 ULCTX POLY DCT TX A2 B1 ADD ULCTX POLY DCT TX A3 Bl MUL1 ULCTX POLY DCT TX A3 B1 MUL2 ULCTX POLY DCT TX A3 Bl ADD_ULCTX POLY DCT TX AO B2 MUL1 ULCTX POLY DCT TX AO B2 MUL2 ULCTX POLY DCT TX AO B2 ADD_ULCTX POLY DCT
47. iptions Table 7 DES CBC CRYPT REQ Valid Descriptors op1d Descriptors Value DPD SDES CBC CTX ENCRYPT 0x2500 DPD SDES CBC CTX DECRYPT 0x2501 DPD TDES CBC CTX ENCRYPT 0x2502 DPD TDES CBC CTX DECRYPT 0x2503 4 2 2 DES CRYPT REQ COMMON REQ PREAMBLE unsigned long keyBytes 8 16 or 24 bytes unsigned char keyData unsigned long inBytes unsigned char inData unsigned char outData NUM DES Les multiple of 8 bytes Function Description Load encrypted context from a dynamic channel to encrypt in single DES using CBC mode Load encrypted context from a dynamic channel to decrypt in single DES using CBC mode Load encrypted context from a dynamic channel to encrypt in triple DES using CBC mode Load encrypted context from a dynamic channel to decrypt in triple DES using CBC mode output length input length ESC 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 Descriptors DPD_SDES ECB ENCRYPT DPD SDES ECB DECRYPT DPD TDES ECB ENCRYPT DPD TDES ECB DECRYPT Table 8 DES CRYPT REQ Valid Descriptors op1d Value 0x2600 0x2601 0x2602 0x2603 4 3 ARC4 Requests 4 3 1 ARC4 LOADCTX CRYPT REQ COMMON REQ PREAMBLE unsigned long inCtxBytes 257 bytes Function Description Encrypt data in single DES using E
48. iptors within this request Table 20 ECC_POINT REQ Valid Descriptors op1d Descriptors Value DPD EC FP AFF PT MULT 0x5800 DPD EC FP PROJ PT MULT 0x5801 DPD EC F2M AFF PT MULT 0x5802 DPD EC F2M PROJ PT MULT 0x5803 DPD EC FP LDCTX ADD ULCTX 0x5804 DPD EC FP LDCTX DOUBLE ULCTX 0x5805 DPD EC F2M LDCTX ADD ULCTX 0x5806 DPD EC F2M LDCTX DOUBLE ULCTX 0x5807 4 8 2 ECC 2OP REQ COMMON REQ PREAMBLE unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned NUM EC 2OP D long char long char long char long char bDa bDa aDa aDa taBytes ta taBytes ta modBytes mod Data outBytes out Data Function Description Perform a PT_MULT operation in an affine system Perform a PT_MULT operation in a projective system Perform an F2M PT_MULT operation in an affine system Perform an F2M PT MULT operation in a projective system Perform an FP add operation Perform an FP double operation Perform an F2M add operation Perform an F2M double operation ESC defines the number of descriptors within the DPD EC 20P GROUP that use this request SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 25 Individual Request Type Descriptions DPD EC 20P GROUP 0x5900 defines the group for all descriptors within this request Table 21 ECC 20P REQ Valid
49. m 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 long cryptKeyBytes unsigned char cryptKeyData unsigned long cryptCtxInBytes unsigned char cryptCtxInData unsigned long hashInDataBytes unsigned char hashInData
50. nsigned long bl1DataBytes unsigned char b2Data unsigned long b2DataBytes unsigned char b2Data unsigned long b3DataBytes unsigned char b3Data Individual Request Type Descriptions Table 23 ECC PTADD DBL_REQ Valid Descriptor opId Descriptor DPD_EC_FPADD DPD_EC_FPDBL DPD_EC_F2MADD DPD EC F2MDBL 4 9 IPSec Requests 4 9 1 IPSEC CBC REQ COMMON REQ PREAMBLE unsigned long hashKeyBytes unsigned char hashKeyData unsigned long cryptKeyBytes unsigned char cryptKeyData unsigned long cryptCtxInBytes Value 0x5d00 Ox5d01 0x5d02 0x5d03 Function Description Perform an FP add operation Perform an FP double operation Perform an F2M add operation Perform an F2M double operation SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Individual Request Type Descriptions unsigned unsigned unsigned unsigned unsigned unsigned unsigned unsigned NUM IPSEC CBC D request DPD IPSEC CBC G Descriptor DPD IPSEC char long char long char char long char cryptCtxInData hashInDataBytes CBC hashInData inDataBytes inData teryptDataOut hashDataOutBytes hashDataOut ESC defines the number of descriptors within the DPD_IPSEC_CBC_GROUP that use this ROUP 0x7000 defines the group for all descriptors within this request Table 24 IPSEC_CBC_REQ Valid Des
51. ocess an inbound SRTP packet 5 Sample Code The following sections provide sample codes for DES and IPSec 5 1 DES Sample define the User Structure DES LOADCTX CRYPT REQ desencReq fill the User Request structure with appropriate pointers desencReq opId DPD 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 36 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor desencReq desencReq desencReq desencReq desencReq desencReq desencReq desencReq desencReq status 0 ivBytes 8 input iv length ivData iv_in pointer to input iv keyBytes 24 key length keyData DesKey pointer to Rey inBytes packet length data length inData DesData pointer to data outData desEncResult pointer to results nextReg 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 desencReq status 0 5 2 IPSEC Sample define User Requests structures IPSEC CBC REQ ipsecReq Ipsec ipsec ipsec
52. on Perform the IPSec process of encrypting in AES using CBC mode with MD5 auto padding Perform the IPSec process of encrypting in AES using CBC mode with SHA 1 auto padding Perform the IPSec process of encrypting in AES using CBC mode with SHA 256 auto padding SEC 2 0 Reference Device Driver User s Guide Rev 0 30 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor DPD DPD DPD DPD DPD DPD DPD DPD DPD Individual Request Type Descriptions Table 26 IPSEC AES CBC REQ Valid Descriptors opId continued Descriptors Value Function Description IPSEC AES CBC ENCRYPT MD5 0x8003 Perform the IPSec process of encrypting in AES using CBC mode with MD5 IPSEC AES CBC ENCRYPT SHA 0x8004 Perform the IPSec process of encrypting in AES using CBC mode with SHA 1 IPSEC AES CBC _ ENCRYPT SHA256 0x8005 Perform the IPSec process of encrypting in AES using CBC mode with SHA 256 IPSEC AES CBC DECRYPT MD5 APAD 0x8006 Perform the IPSec process of decrypting in AES using CBC mode with MD5 auto padding IPSEC AES CBC DECRYPT SHA APAD 0x8007 Perform the IPSec process of decrypting in AES using CBC mode with SHA 1 auto padding IPSEC AES CBC DECRYPT SHA256 APAD 0x8008 Perform the IPSec process of decrypting in AES using CBC mode with SHA 256 auto padding IPSEC AES CBC DECRYPT MD5 0x8009 Perform the IPSec process of decrypting in AES using CBC mode with MD5 IPSEC AES CBC DECRYPT
53. ong unsigned char unsigned long unsigned char unsigned char unsigned long unsigned char keyBytes keyData inIvBytes inIvData inBytes inData outData outCtxBytes outCtxData 16 24 or 32 bytes 0 or 16 bytes multiple of 8 bytes Function Description Load context then use an SHA 256 hash algorithm then store the resulting HMAC context Load context then use an MD5 hash algorithm then store the resulting HMAC context Load context then use an SHA 1 hash algorithm then store the resulting HMAC context Load context then use an SHA 256 IDGS hash algorithm then store the resulting padded HMAC context Load context then use an MD5 IDGS hash algorithm then store the resulting padded HMAC context Load context then use an SHA 1 IDGS hash algorithm then store the resulting padded HMAC context output length input length 0 or 8 bytes 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 SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 19 Individual Request Type Descriptions Table 14 AESA CRYPT REQ Valid Descriptors op1d Descriptors Value DPD AESA CBC ENCRYPT CRYPT 0x6000 DPD AESA CBC DECRYPT C
54. quests together e It is the application s choice to use a notifier function or to poll the status member SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 5 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 function 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 the ioct1 function and the second one after the completion of the request The second level is possible only if the request was done with at least the notify_on_error member of the user request structure If the notification callback function has not been requested 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 CRY aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn aesdyn status if status Req Req Req Req Req prin
55. rator This term is synonymous with AESU in the MPC 18x User s Manual and other documentation AFHA ARC 4 hardware accelerator This term is synonymous with AFEU in the MPC 18x User s Manual and other documentation APAD Autopad The MDHA will automatically pad incomplete message blocks out to 512 bits vhen 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 MPC 18x User s Manual and other documentation CTX Context DESA DES accelerator This term is synonymous with DEU in the MPC 18x User s Manual and other 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 KEA Kasumi encryption acceleration MD Message digest MDHA Message digest hardware accelerator This term is synonymous with MDEU in the MPC 18x User s Manual and other documentation OS Operating system PR Public Rey PRHA Public key hardware accelerator This term is synonymous with PREU in the MPC 18x User s Manual and other documentation SEC 2 0 Reference Device Driver User s Guide Rev 0
56. shell 2 Execute torVars to set up the Tornado command line build environment 3 Run make in the driver or test installation directory by use of the following command make CPU cpuFamily TOOL toolChain SP securityProcessor xample make CPU PPC85XX TOOL gnu SP SEC2 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 SEC2 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 has been ported to function on both VxWorks and
57. spatch routine provides the ioct1 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 data packet descriptor 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 deferred service routine SEC 2 0 Reference Device Driver User s Guide Rev 0 4 PRELIMINARY SUBJECT TO CHA
58. st 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 testAll 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 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 6 2 3 Driver Module License Macro A common necessity of loadable modules for Linux is the inclusion of a license macro MODULE_LICENSE that declares a string defining the type of license terms under which the module s code has been published In the case of the SEC2 driver module this code is delivered in source form under the terms of a restricted license agreement Therefore this macro has been passed a name of Freescale Restricted to acknowledge the existence of this agreement When loading the driver object the existence of a non GPL non BSD license string will cause a warning message to be printed to
59. sue of the user s request unsigned long unsigned char unsigned char unsigned char unsigned char PSEC2 NOTIFY ROUTINE PSEC2 NOTIFY CTX OpId scatterBufs notifyFlags reserved channel notify pNotifyCtx PSEC2 NOTIFY ON ERROR ROUTINE notify on error SEC2 NOTIFY ON ERROR CTX ctxNotifyOnErr int status void nextReq opid operation Id which identifies what type of request this is It is normally associated with scatterBufs notifyFlags channel notify pNotifyCtx a specific type of cryptographic operation see Section 4 Individual Request Type Descriptions for all supported request types A bitmask 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 Section 3 3 7 Scatter Gather Buffer Management If a POSIX style signal handler will be responsible for request completion notification then it can contain ORed bits of NOTIFY IS PID and or NOTIFY ERROR IS PID signifying that the notify ornotify on error pointers are instead the process ID s i e get pid of the task requesting a signal upon request completion identifies the channel to be used for the request It exists for legacy compatibility reasons and is no longer useful for SEC2 pointer to a notification callback routine that will be called when the request has completed successfully May instead
60. t 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 an 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 opId DPD TDES CBC CTX ENCRYPT encReq notify notifier encReg notify on error notifier encReq inIvBytes 8 encReq 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 SOEX encReq outData unsigned char output this buffer is scattered MarkScatterBuffer amp encReq amp encReq input MarkScatterBuffer amp encReq amp encReq output 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 SEC 2 0 Re
61. tf Req Req Req Req Req Req Req Req Req Req PT REQ aesdynReq opId DPD AESA CBC ENCRYPT CRYPT channel 0 notify void notifAes notify on error void notifAes status Ds inIvBytes 8 163 inIvData iv_in keyBytes 324 ReyData AesKey inBytes packet length inData aesData outData aesResult outIvBytes 16 outIvData iv_out nextReq EnO Ioct1 device IOCTL PROC REQ amp aesdynReq l 0 Syntax Logic Error in dynamic descriptor 0x x n status y g y P SEC 2 0 Reference Device Driver User s Guide Rev 0 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor User Interface in callback function notifAes if aesdynReq status 0 printf Error detected by HW 0x x n aesdynReq status 3 3 Global Definitions 3 3 1 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 value of 0x0800 Table 2 Second and Third Arguments in the ioct1 Function I O Control Code Second Argument in ioct1 Function Third Argument in ioct1 Function SEC2 PROC REQ Pointer to user s request structure SEC2 GET STATUS Pointer to a STATUS_REQ
62. the request index or descriptor within a group or type This is provided to help understand the structuring of the oplds It is not specifically needed within a user application Table 4 Request Operation ID Mask Define Description Value DESC_TYPE MASK The mask for the group or type of an opld OxFFOO DESC NUM MASK The mast for the request index or descriptor vvithin that group or type OxOOFF 3 3 4 Return Codes A complete list of the error status results that may be returned to the callback routines follows Table 5 Callback Error Status Return Code Define Description Value SEC2 SUCCESS Successful completion of request 0 SEC2 MEMORY ALLOCATION Driver can t obtain memory from the host operating OxEQO4FFFF system SEC2 INVALID CHANNEL Channel specification was out of range This exists for OXE004FFFE legacy compatibility and has no relevance for SEC2 SEC2 INVALID CHA TYPE Requested CHA doesn t exist OxE004FFFD SEC2 INVALID OPERATION ID Requested opID is out of range for this request type OXE004FFFC SEC2 CHANNEL NOT AVAILABLE Requested channel was not available This error 0xE004FFFB exists for legacy compatibility reasons and has no relevance for SEC2 SEC 2 0 Reference Device Driver User s Guide Rev 0 8 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE Freescale Semiconductor User Interface Table 5 Callback Error Status Return Code continued Define Description Value SEC2 CHA NOT AVAILABLE Requested CHA was not
63. ts their preference Logical to physical memory space translation is handled internal to the driver SEC 2 0 Reference Device Driver User s Guide Rev 0 Freescale Semiconductor PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE 39 VxWorks Environment 6 2 2 Driver Operation in User Mode Operation of the SEC2 device 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 1 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_MALLOC SEC2_FREE SEC2_COPYFROM and SEC2_COPYTO requests see Section 3 3 1 I O Control Codes for more information Note 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 2 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 reque

Freescale Semiconductor SEC2SWUG User's Manual

Contents

Download Pdf Manuals

Related Search

Related Contents