API Reference

Trust Anchor Specific API

Include file: <mi.h> | Linker switch: -lmi


Debugging

miDebuggingDisable
miDebuggingEnable

Embedded Events

miDeregisterEmbeddedEvent
miEnableEmbeddedLowPowerMode
miFlushEmbeddedEvent
miFlushEmbeddedEventWithInfo
miGetEmbeddedEventId
miGetEmbeddedEventInfo
miSetEmbeddedInterfaceType
miSetEmbeddedPowerMode
miRegisterEmbeddedEvent
miSetContactlessBehaviour
miSetEarlyCombinedModeStartupEvents
miVccPowerApplied

Fault Processing

miAbendReason
miPerformHalt
miPerformRestart
miSetAbendFunction

GPIO

miGPIOAllocatePin
miGPIOAllocatePins
miGPIOAllocateStartupPin
miGPIOClearMonitoredPinEvent
miGPIODeallocateStartupPin
miGPIOEnableOutputPin
miGPIOEnableOutputPins
miGPIOEnablePullupPin
miGPIOEnablePullupPins
miGPIOMonitoredPinEventOccurred
miGPIOMonitorPin
miGPIOReadPin
miGPIOReadPort
miGPIOSetPin
miGPIOSetPort
miGPIOSetStartupPin
miGPIOUnmonitorPin

I2C

miI2CInitialise
miI2CReceiveByte
miI2CRegisterAccess
miI2CRegisterReadByte
miI2CRegisterReadBytes
miI2CRegisterWriteByte
miI2CRestrictBuffers
miI2CRegisterWriteBytes
miI2CSetPeripheralAddress
miI2CSlaveGetNumReceivedBytes
miI2CSlaveGetReceivedBytes
miI2CSlaveInitialise
miI2CSlaveSetAutoReadRegister
miI2CSlaveTransmitBytes
miI2CStart
miI2CStop
miI2CTransmitByte

I2C Types


Integrity Checking

miPerformIntegrityCheck

Printing

sprintf

Serial IO

miSerialIOFlushReceiveBuffer
miSerialIOGetNumReceivedBytes
miSerialIOGetReceiveBufferState
miSerialIOGetReceivedBytes
miSerialIOInitialise
miSerialIORestrictBuffers
miSerialIOSetActivePort
miSerialIOTransmitBytes

SPI

miSPIInitialise
miSPIRestrictBuffers
miSPISetSlave
miSPITransmitReceive

Timers

miDelay
miDelayJitter
miTimerCreate
miTimerExpired
miTimerFree
miTimerPause
miTimerRead
miTimerResume
miTimerStart
miWatchdogInitialise
miWatchdogRefresh

Version

miGetLibraryVersion

Standard MULTOS C-API

This is a cutdown version of the standard MULTOS C-API including the functionality most needed for the Trust Anchor product.Include file: <multos.h> | Linker switch: None (included by default)


Arithmetic and Logic

multosAdd
multosAnd
multosBCDtoBIN
multosBINtoBCD
multosCheckBCD
multosDecrement
multosDivide
multosIncrement
multosInvert
multosMultiply
multosOr
multosRotateLeft
multosRotateRight
multosShiftLeft
multosShiftRight
multosSubtract
multosSubtractBCD
multosTestZero
multosXor

Program Flow

multosCallCodelet
multosCallExtensionPrimitive
multosCheckCase
multosDelegate
multosExit
multosExitLa
multosExitSW
multosExitSWLa
multosGetDelegatorAID
multosGetProcessEvent
multosRejectProcessEvent
multosRestoreStack
multosReturnFromCodelet
multosSaveStack

System

multosCardBlock
multosCardUnBlock
multosGetAID
multosGetConfigData
multosGetData
multosGetDIRFile
multosGetFCI
multosGetFCIState
multosGetManufacturerData
multosGetMultosData
multosQueryCodelet
multosQueryCryptographicAlgorithm
multosQueryPrimitive

Cryptography

multosChecksum
multosDecipherCBC
multosDecipherECB
multosEccGenerateKeyPair
multosECDH
multosECDSA
multosECDSAVerify
multosEncipherCBC
multosEncipherECB
multosGenerateDESCBCSignature
multosGenerateMAC
multosGenerateRsaKeyPair
multosGenerateTripleDESCBCSignature
multosGetRandomNumber
multosModularExponentiation
multosModularExponentiationCRT
multosPad
multosPlatformOptimisedChecksum
multosRsaVerify
multosSecureHash
multosSecureHashIV
multosSHA1
multosUnPad

Memory

multosClear
multosCompare
multosCompareEnhanced
multosCopy
multosCopyFixedLength
multosCopyFromAdditionalStatic
multosCopySessionFromReplacedApp
multosCopyStaticFromReplacedApp
multosCopyToAdditionalStatic
multosCopyWithinAdditionalStatic
multosFillAdditionalStatic
multosGetReplacedAppState
multosGetSessionSize
multosGetStaticSize
multosGetTransactionState
multosIndex
multosLookup
multosLookupWord
multosResetSessionData
multosSetProtectedMemoryAccess
multosSetTransactionProtection
multosUpdateSessionSize
multosUpdateStaticSize

PIN Management

multosGetPINStatus
multosGetPINTryCounter
multosGetPINTryLimit
multosInitialisePIN
multosInitialisePINExtended
multosGetPINVerificationStatus
multosReadPIN
multosSetPINTryCounter
multosSetPINTryLimit
multosSetPINVerificationStatus
multosVerifyPIN

C Language Support

ctype.h

isalpha
isupper
islower
isdigit
isspace
ispunct
isalnum
isprint
isgraph
iscntrl

stdio.h

printf**

stdlib.h

abs
div
labs
ldiv
calloc*
malloc*
realloc*
free*
itoa
ltoa
ultoa

heap.h

heap_init
heap_used

string.h

memcpy
memmove
memcmp
memchr
memset***
strcpy
strncpy
strcat
strncat
strcmp
strncmp
strchr
strcspn
strpbrk
strrchr
strspn
strstr
strlen

Notes:

* There is no heap as such in MULTOS as applications have to define their memory usage during the loading process. However it is possible to pre-allocate an area of memory as heap using the functions in <heap.h> allowing malloc etc. to be used.

** printf will output to console when using the simulator or to the default serial port when running in the chip.

*** It is much faster to use multosClear than memset to set a block of memory to zero.


Debugging

Debugging Functions

miDebuggingDisable


void miDebuggingDisable (void);


Description

Disables ~SmartDeck debugging. Currently unsupported (does nothing).

Abend Conditions

None.

miDebuggingEnable


void miDebuggingEnable (void);


Description

Enables ~SmartDeck debugging.

Abend Conditions

None.

Embedded Events

Embedded Event Constants

MI_DISABLE_EARLY_STARTUP_EVENTS

Disable early startup events.

MI_DISABLE_PROCESSING_CONTACTLESS_CHANGES

Disable the processing of any contactless changes.

MI_EMBEDDED_EVENT_GPIO

A GPIO embedded event – a monitored GPIO pin has changed state.

MI_EMBEDDED_EVENT_I2C_SLAVE

An I2C slave embedded event – an event has occurred over the slave I2C interface.

MI_EMBEDDED_EVENT_NONE

Not an embedded event – the event is a smartcard event.

MI_EMBEDDED_EVENT_SERIAL_IO

A serial IO embedded event – a monitored serial channel event has occurred.

MI_EMBEDDED_EVENT_STARTUP

A startup embedded event – MULTOS has started or restarted.

MI_EMBEDDED_EVENT_STARTUP_POWERUP_VCC

A Vcc powerup emedded event – MULTOS has started oro restarted following power being applied to the Vcc pin with no contactless field present or following the loss of a contactless field with Vcc pin powered up.

MI_EMBEDDED_EVENT_STARTUP_POWERUP_VCC_CONTACTLESS

A Vcc contactless powerup emedded event – MULTOS has started or restarted following power being applied to the Vcc pin with a contactless field present or a contactless field being applied with the Vcc pin powered up.

MI_EMBEDDED_EVENT_STARTUP_RESTART_EXCEPTION

An exception restart event – MULTOS has restarted due to a system exception.

MI_EMBEDDED_EVENT_STARTUP_RESTART_INTEGRITY

An integrity restart event – MULTOS has restarted due to an integrity failure.

MI_EMBEDDED_EVENT_STARTUP_RESTART_WATCHDOG

An watchdog restart event – MULTOS has restarted due to a watchdog failure.

MI_EMBEDDED_EVENT_TIMER

A timer embedded event – a monitored timer has expired.

MI_ENABLE_EARLY_STARTUP_EVENTS

Enable early startup events.

MI_ENABLE_PROCESSING_CONTACTLESS_CHANGES_AFTER_APP

Enable the processing of any contactless changes once the current application has finished executing.

MI_ENABLE_PROCESSING_CONTACTLESS_CHANGES_NOW

Immediately enable the processing of any contactless changes.

MI_EVENT_EMBEDDED

Embedded Event Functions

miDeregisterEmbeddedEvent


void miDeregisterEmbeddedEvent (BYTE eventId, BYTE eventInfo);


Description

Deregisters the application to the specified embedded event.

Parameters

Abend Conditions

  • Invalid event ID.
  • Invalid event information.

miEnableEmbeddedLowPowerMode


void miEnableEmbeddedLowPowerMode (void);


Description

Enables embedded low power mode until next reset. When in embedded low power mode MULTOS enters a low power -halt- mode if applications are waiting to receive and process embedded events, helping to reduce the current consumption of the SLE78 in this idle state. This has no effect on the power consumption when MULTOS is running in Contact Smartcard Mode or Contactless Smartcard Mode: it is always in this low power -halt- mode when waiting to receive a command APDU.

Abend Conditions

None.

Note

When in low power mode at least one MULTOS application should run a periodic countdown timer as this will make MULTOS check for new embedded events at this time. This prevents rare race conditions that would result in MULTOS not executing applications even though a new embedded event has been received. Applications should choose the right wakeup time: the shorter the time the reduced possible latency but at the cost of higher power consumption.

miFlushEmbeddedEvent


void miFlushEmbeddedEvent (BYTE eventId);


Description

Flushes an event from the event queue.

Parameters

Abend Conditions

None.

miFlushEmbeddedEventWithInfo


void miFlushEmbeddedEventWithInfo (BYTE eventId, BYTE eventInfo);


Description

Flushes an event/info combination from the event queue.

Parameters

Abend Conditions

None.

miGetEmbeddedEventId


BYTE miGetEmbeddedEventId (void);


Description

Returns the latest embedded event ID.

Return Value

The latest embedded event ID – one of:

Abend Conditions

None.

miGetEmbeddedEventInfo


BYTE miGetEmbeddedEventInfo (void);


Description

Returns the information associated with the latest event.

Return Value

The latest embedded event information. This depends on the event ID as follows:

Abend Conditions

None.

miSetEmbeddedInterfaceType


void miSetEmbeddedInterfaceType (BYTE interface);


Description

Sets the value to be returned by multosQueryInterfaceType() when MULTOS is in embedded mode.

Parameters

  • interface – the interface type to be returned:
    • MI_EMBEDDED_INTERFACE_TYPE_DEFAULT – the default value
    • MI_EMBEDDED_INTERFACE_TYPE_CONTACT – multosQueryInterfaceType() indicates that the contact interface is active.
    • MI_EMBEDDED_INTERFACE_TYPE_CONTACTLESS – multosQueryInterfaceType() indicates that the contactless interface is active.

Abend Conditions

  • Invalid interface value.

miSetEmbeddedPowerMode


void miSetEmbeddedPowerMode (BYTE mode);


Description

Sets the power mode of MULTOS when it’s waiting to process an embedded event.

Parameters

  • mode – the required power mode:
    • MI_EMBEDDED_POWER_MODE_NORMAL
    • MI_EMBEDDED_POWER_MODE_LOW
    • MI_EMBEDDED_POWER_MODE_ULTRA_LOW

Abend Conditions

  • Invalid mode value.

Notes

Calling this function with the value MI_EMBEDDED_POWER_MODE_LOW is equivalent to calling miEnableEmbeddedLowPowerMode.

If this function is called with the parameter MI_EMBEDDED_POWER_MODE_ULTRA_LOW then all timers stop running and no

applications will receive timer events until the embedded power mode is set to MI_EMBEDDED_POWER_MODE_NORMAL or

MI_EMBEDDED_POWER_MODE_LOW. This is because MULTOS deactivates the chip’s timers to conserve power consumption.

miRegisterEmbeddedEvent


void miRegisterEmbeddedEvent (BYTE eventId, BYTE eventInfo);


Description

Registers the application to the specified embedded event.

Parameters

Abend Conditions

  • Invalid event ID.
  • Invalid event information.

miSetContactlessBehaviour


void miSetContactlessBehaviour (BYTE behaviour);


Description

Sets the contactless behaviour.

By default contactless field changes (i.e. a contactless field being applied or removed) causes MULTOS to reset immediately. If this behaviour is not desirable (because, for example, your application is performing a critical operation much must not be interrupted) then this function allows you to temporarily disable it for a specific period.

Parameters

Abend Conditions

  • Invalid behaviour value.

Notes

This function controls the behaviour of MULTOS in Embedded Mode and Combined Mode differently as described below.

When MULTOS is in Embedded Mode applying a contactless field will cause MULTOS to reset immediately to allow it to process the contactless communications. By calling miSetContactlessBehaviour your application can temporarily disable this automatic resetting of MULTOS. You need to be aware though that while the processing of contactless changes has been disabled any contactless smartcard reader will not be able to select and communicate with your device. For this reason we recommend that you design your application in such a way that the length of this period is minimised.

When MULTOS is in Combined Mode removing the contactless field will cause MULTOS to reset immediately. By calling miSetContactlessBehaviour your application can temporarily disable this automatic resetting of MULTOS, although because of the way the contactless communications work this needs to be done correctly to prevent any contactless communication failures. This requires your application to call multosControlAutoResetWWT and multosResetWWT as follows:


multosControlAutoResetWWT (TRUE); // Disable the automatic generation of wait time extension (WTX) messages

multosResetWWT (); // Issue a WTX to maximise the non-interruptable procesing time

miSetContactlessBehaviour (MI_DISABLE_PROCESSING_CONTACTLESS_CHANGES); // Disable contactless change processing

// Perform your non-interruptable operations here

miSetContactlessBehaviour (MI_ENABLE_PROCESSING_CONTACTLESS_CHANGES_NOW); // Enable contactless change processing

multosControlAutoResetWWT (FALSE); // Enable the automatic generation of wait time extension (WTX) messages


By doing this the non-interruptable operations will run to completion regardless of whether the contactless field is removed. Note however the non-interruptable operations must be completed within your device-s frame waiting time (FWT). The FWT is set when MULTOS is enabled and is typically 38.5ms (but can be more).

miSetEarlyCombinedModeStartupEvents


void miSetEarlyCombinedModeStartupEvents (BYTE behaviour);


Description

Permanently enables/disables early combined mode startup events.

When MULTOS is running in combined mode (i.e. with both Vcc and contactless applied) the MI_EMBEDDED_EVENT_STARTUP startup event is normally generated during the processing of the first received APDU following reset. If required, you can change this behaviour so that the startup event is generated immediately following the ATS or Answer to ATTRIB messages.

Warning: You should be careful when using this function. If your application takes too long to process the startup event then the contactless ISO-14443 timings my become invalid which could cause contactless readers to fail when used to access your device.

Parameters

Abend Conditions

  • Invalid behaviour value.

miVccPowerApplied


BOOL miVccPowerApplied (void);


Description

Returns TRUE if power is applied to the Vcc pin.

Abend Conditions

None.

Fault Processing

Fault Processing Constants

MI_ABEND_REASON_CRYPTO_ERROR

Cryptographic error.

MI_ABEND_REASON_CRYPTO_NOT_PERMITTED

Application not authorised to use strong crypto.

MI_ABEND_REASON_FIREWALL_VIOLATION

Firewall violation.

MI_ABEND_REASON_GP_NO_PERMISSION

Global PIN access level error.

MI_ABEND_REASON_GP_PIN_ALREADY_INIT

Global PIN already initialised.

MI_ABEND_REASON_GP_PIN_NOT_INIT

Global PIN not initialised.

MI_ABEND_REASON_GP_PTC_PTL

Global PIN PTC greater then PTL.

MI_ABEND_REASON_INVALID_CODELET_RET

Invalid codelet return.

MI_ABEND_REASON_INVALID_OPTION

Invalid instruction/primitive option.

MI_ABEND_REASON_INVALID_PARAMETER

Invalid instruction/primitive parameter.

MI_ABEND_REASON_MEL_PRIM_CALL_DEPTH

Maximum MEL primitive call depth exceeded.

MI_ABEND_REASON_NO_ABEND

No abend.

MI_ABEND_REASON_NOT_ENOUGH_NVM

Insufficient NVM.

MI_ABEND_REASON_NOT_ENOUGH_RAM

Insufficient RAM.

MI_ABEND_REASON_PERIPHERAL_NO_PERMISSION

Application does not have permission to access the requested peripheral

MI_ABEND_REASON_PRECONDITIONS_NOT_MET

Instruction/primitive preconditions not met.

MI_ABEND_REASON_RESTRICTIONS_NOT_MET

Instruction/primitive restrictions not met.

MI_ABEND_REASON_SYSTEM_ERROR

System error.

MI_ABEND_REASON_UNKNOWN_CODELET

Unknown codelet.

MI_ABEND_REASON_UNKNOWN_INSTRUCTION

Unknown MEL instruction.

MI_ABEND_REASON_UNKNOWN_PRIMITIVE

Unknown MEL primitive.

Fault Processing Functions

miAbendReason


BYTE miAbendReason (void);


Description

Returns a code which specifies the reason for the abend.

Return Value

The abend reason as follows:

Abend Conditions

None.

miPerformHalt


void miPerformHalt (void);


Description

Makes MULTOS halt until the next reset.

Abend Conditions

None.

miPerformRestart


void miPerformRestart (void);


Description

Makes MULTOS restart.

Abend Conditions

None.

Note

Performing a restart caused the SLE78 to refresh its security features and for this reason we recommend that security-critical embedded systems are restarted periodically.

miSetAbendFunction


void miSetAbendFunction (WORD abendAddress);


Description

Sets the abend function.

Parameters

  • abendAddress: the start address of the abend function in the currently executing application.

Abend Conditions

None

GPIO

GPIO Constants

MI_GPIO_EVENT_HIGH_LEVEL

The high level event of a GPIO pin.

MI_GPIO_EVENT_HIGH_TO_LOW

A high to low transition event on a GPIO pin.

MI_GPIO_EVENT_LOW_LEVEL

The low level event of a GPIO pin.

MI_GPIO_EVENT_LOW_TO_HIGH

A low to high transition event on a GPIO pin.

MI_GPIO_PIN_STATE_HIGH

The output state of a GPIO pin when driven to Vcc_GPIO.

MI_GPIO_PIN_STATE_LOW

The output state of a GPIO pin when driven to GND.

MI_GPIO_PIN_STATE_OUTPUT_DISABLED

The output state of a GPIO when its output is disabled.

MI_PACKAGE_PIN_2_GPIO_PIN_NUMBER

The GPIO pin number of package pin 2.

MI_PACKAGE_PIN_26_GPIO_PIN_NUMBER

The GPIO pin number of package pin 26.

MI_PACKAGE_PIN_27_GPIO_PIN_NUMBER

The GPIO pin number of package pin 27.

MI_PACKAGE_PIN_28_GPIO_PIN_NUMBER

The GPIO pin number of package pin 28.

MI_PACKAGE_PIN_29_GPIO_PIN_NUMBER

The GPIO pin number of package pin 29.

MI_PACKAGE_PIN_3_GPIO_PIN_NUMBER

The GPIO pin number of package pin 3.

MI_PACKAGE_PIN_30_GPIO_PIN_NUMBER

The GPIO pin number of package pin 30.

MI_PACKAGE_PIN_31_GPIO_PIN_NUMBER

The GPIO pin number of package pin 31.

MI_PACKAGE_PIN_4_GPIO_PIN_NUMBER

The GPIO pin number of package pin 4.

MI_PACKAGE_PIN_5_GPIO_PIN_NUMBER

The GPIO pin number of package pin 5.

MI_PACKAGE_PIN_6_GPIO_PIN_NUMBER

The GPIO pin number of package pin 6.

MI_PACKAGE_PIN_7_GPIO_PIN_NUMBER

The GPIO pin number of package pin 7.

GPIO Functions

miGPIOAllocatePin


void miGPIOAllocatePin (BYTE pin);


Description

Allocates a GPIO pin.

Parameters

  • pin: the GPIO pin to allocate.
  • Abend Conditions
  • GPIO pin number > 11.
  • GPIO pin already allocated.

miGPIOAllocatePins


void miGPIOAllocatePins (BYTE port, BYTE pins);


Description

Allocates a number of GPIO pins associated with a port.

Parameters

  • port: the GPIO port.
  • pins: a bitmap of the GPIO pins to allocate – if a bit is set then the corresponding pin is allocated.

Abend Conditions

  • GPIO port number > 1.
  • GPIO pin(s) already allocated.

miGPIOAllocateStartupPin


void miGPIOAllocateStartupPin (BYTE num, BYTE pin, BYTE state);


Description

Permanently allocates a startup GPIO pin.

Parameters

Abend Conditions

  • Startup pin number > 1.
  • GPIO pin number > 11.
  • GPIO pin already allocated.
  • Invalid state.

miGPIOClearMonitoredPinEvent


void miGPIOClearMonitoredPinEvent (BYTE pin);


Description

Clears the monitored pin event associated with the specified pin.

Parameters

  • pin: the GPIO pin.

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.

miGPIODeallocateStartupPin


void miGPIODeallocateStartupPin (BYTE num);


Description

Permanently deallocates a startup GPIO pin.

Parameters

  • num: the startup pin number (0 or 1)

Abend Conditions

  • Startup pin number > 1.

miGPIOEnableOutputPin


void miGPIOEnableOutputPin (BYTE pin);


Description

Sets a GPIO pin as an output.

Parameters

  • pin: the GPIO pin to set as an output.

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.

miGPIOEnableOutputPins


void miGPIOEnableOutputPins (BYTE port, BYTE pins);


Description

Sets a number of GPIO pins as outputs.

Parameters

  • port: the GPIO port.
  • pins: a bitmap of the GPIO pins to set as outputs – if a bit is set then the corresponding pin is an output.

Abend Conditions

  • GPIO port number > 1.
  • GPIO pin(s) not allocated.

miGPIOEnablePullupPin


void miGPIOEnablePullupPin (BYTE pin);


Description

Enables the internal pull-up resistor for a GPIO pin.

Parameters

  • pin: the GPIO pin to enable internal pull-up resistor for.

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.

miGPIOEnablePullupPins


void miGPIOEnablePullupPins (BYTE port, BYTE pins);


Description

Enables the internal pull-up resistor for a number of GPIO pins.

Parameters

  • port: the GPIO port (0 or 1).
  • pins: a bitmap of the GPIO pins to enabled the internal pull-up resistors for – if a bit is set then the corresponding pin has its internal pull-up resistor enabled.

Abend Conditions

  • GPIO port number > 1.
  • GPIO pin(s) not allocated.

miGPIOMonitoredPinEventOccurred


BOOL miGPIOMonitoredPinEventOccurred (BYTE pin);


Description

Indicates whether a GPIO pin event has occurred.

Parameters

  • pin: the GPIO pin to query.

Return Value

  • FALSE = GPIO event not occurred.
  • TRUE = GPIO event occurred.

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.

miGPIOMonitorPin


void miGPIOMonitorPin (BYTE pin, BYTE event);


Description

Enables the monitoring of a pin for a specific event.

Parameters

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.
  • Invalid GPIO event.

miGPIOReadPin


BYTE miGPIOReadPin (BYTE pin);


Description

Reads the value of a GPIO pin.

Parameters

  • pin: the GPIO pin to read.

Return Value

  • 0 = low state.
  • 1 = high state.

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.

miGPIOReadPort


BYTE miGPIOReadPort (BYTE port);


Description

Reads the value of a GPIO port.

Parameters

  • port: the GPIO port (0 or 1).

Return Value

The port-s value: each allocated bit is set to 0 or 1 with unallocated bits set to 0.

Abend Conditions

  • GPIO port number > 1.

miGPIOSetPin


void miGPIOSetPin (BYTE pin, BYTE state);


Description

Sets the state of a GPIO pin.

Parameters

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.
  • Invalid state.

miGPIOSetPort


void miGPIOSetPort (BYTE port, BYTE value);


Description

Sets the output state of a port.

Parameters

  • port: the GPIO port.
  • value: a bitmap of the GPIO pins to set low or high – if a bit is set then the corresponding output pin is set high.

Abend Conditions

  • GPIO port number > 1.

miGPIOSetStartupPin


void miGPIOSetStartupPin (BYTE num, BYTE state);


Description

Temporarily sets the startup pin to a specified state.

Parameters

Abend Conditions

  • Startup pin number > 1.
  • Startup pin not allocated.
  • Invalid state.

miGPIOUnmonitorPin


void miGPIOUnmonitorPin (BYTE pin);


Description

Disables the monitoring of a pin.

Parameters

  • pin: the GPIO pin to stop monitoring.

Abend Conditions

  • GPIO pin number > 11.
  • GPIO pin not allocated.

I2C

I2C Functions

miI2CInitialise


void miI2CInitialise (BYTE pinSCL, BYTE pinSDA, BOOL enablePullups);


Description

Initialises the I2C interface in Master mode.

Parameters

  • pinSCL: the SCL GPIO pin number (0-11).
  • pinSDA: the SDA GPIO pin number (0-11).
  • enabledPullups: if TRUE then the internal pull-up resistors are enabled for the SCL and SDA pins.

Abend Conditions

  • The SDA and/or SCL pins are already in use.

miI2CReceiveByte


BYTE miI2CReceiveByte (BOOL ack);


Description

Receives a low-level byte over the I2C interface.

Parameters

  • ack: if TRUE then an ACK should be sent otherwise a NACK bit should be sent.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CRegisterAccess


void miI2CRegisterAccess (BYTE registerAddr);


Description

Accesses an I2C peripheral-s register.

Parameters

  • registerAddr: the I2C-s register address.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CRegisterReadByte


BYTE miI2CRegisterReadByte (BYTE registerAddr);


Description

Reads a byte from an I2C peripheral-s register.

Parameters

  • registerAddr: the I2C-s register address.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CRegisterReadBytes


void miI2CRegisterReadBytes (BYTE registerAddr, BYTE *bytes, WORD numBytes);


Description

Reads a number of bytes from an I2C peripheral-s register.

Parameters

  • registerAddr: the I2C-s register address.
  • bytes: the destination address.
  • numBytes: the number of bytes to read.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CRegisterWriteByte


void miI2CRegisterWriteByte (BYTE registerAddr, BYTE value);


Description

Writes a byte to an I2C peripheral-s register.

Parameters

  • registerAddr: the I2C-s register address.
  • value: the value to write.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CRestrictBuffers


void miI2CRestrictBuffers (BYTE mode);


Description

Controls whether the I2C buffers are to be held in Public.

Parameters

  • mode – whether the I2C buffers are to be held in Public:
    • MI_I2C_BUFFERS_UNRESTRICTED – the buffers can be held in Public, the application’s session data or stack, or in Static (if supported).
    • MI_I2C_BUFFERS_IN_PUBLIC – the buffers can only be held in Public.

Abend Conditions

  • Invalid mode value.

Notes

If an application calls this function to restrict the buffers to Public and then performs an input/output using buffer that is held in Static or in the application’s session or stack then MULTOS abends for the following I2C functions.

  • miI2CRegisterWriteBytes
  • miI2CRegisterReadBytes
  • miI2CSlaveTransmitBytes
  • miI2CSlaveGetReceivedBytes

Following reset MULTOS allows the buffers to be held in Public, the application’s session data or stack, or in Static and applications must call this primitive to restrict them to Public.

Tip

This function should be used by applications if required to make them more robust against fault attack and application memory dumps.

miI2CRegisterWriteBytes


void miI2CRegisterWriteBytes (BYTE registerAddr, BYTE *bytes, WORD numBytes);


Description

Writes a series of bytes to an I2C peripheral-s register.

Parameters

  • registerAddr: the I2C-s register address.
  • bytes: the source address.
  • numBytes: the number of bytes to write.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CSetPeripheralAddress


void miI2CSetPeripheralAddress (BYTE address);


Description

Sets the current I2C peripheral address.

Parameters

  • address: the I2C peripheral address.

Abend Conditions

  • The I2C Master interface has not been initialised.
  • Address > 0x7F.

miI2CSlaveGetNumReceivedBytes


WORD miI2CSlaveGetNumReceivedBytes (void);


Description

Retrieves the number of bytes received over the I2C Slave interface.

Return Value

The number of bytes received over the I2C Slave interface.

Abend Conditions

  • The I2C Slave interface has not been initialised.

miI2CSlaveGetReceivedBytes


WORD miI2CSlaveGetReceivedBytes (BYTE *dest, WORD maxNumBytes);


Description

Retrieves the data received over the I2C Slave interface.

Parameters

  • dest: segment address (in RAM) to copy the data to.
  • maxNumBytes: The maximum number of bytes to copy. If maxNumBytes > the number of bytes received then only the number of bytes received will be copied.

Abend Conditions

  • The I2C Slave interface has not been initialised.
  • dest is not located in application session data, the MEL stack or public.

miI2CSlaveInitialise


void miI2CSlaveInitialise (MI_I2C_SLAVE_CONFIG *config);


Description

Initialises the chip for I2C slave mode.

Parameters

Abend Conditions

  • Invalid pin selection.

miI2CSlaveSetAutoReadRegister


void miI2CSlaveSetAutoReadRegister (BYTE registerAddr, BYTE *bytes, BYTE numBytes);


Description

Sets an automatic slave I2C register read. If numBytes is non-zero then MULTOS makes a copy of the register address and bytes to transmit and when an I2C register read request is performed by the I2C master with a register address that matches the specified register then MULTOS returns the specified bytes on behalf of the application. If numBytes is zero then the auto register read functionality is disabled.

Parameters

  • registerAddr – the address of the I2C register
  • bytes – pointer to the start of the data to be returned
  • numBytes – the number of bytes to return (maximum of 4)

Abend Conditions

  • The I2C slave interface has not been initialised.
  • numBytes is greater than 4.

Tip

Slave I2C applications can used the auto read register to indicate to the I2C master that it is busy processing an operation that could take a relatively long time to process (e.g. and RSA key pair generation). This prevents an I2C lock-up which would occur if the I2C master sends an I2C command to the slave I2C application when it was processing this long operation as the application would only be able to process the I2C message when the operation completed

miI2CSlaveTransmitBytes


void miI2CSlaveTransmitBytes (BYTE *source, WORD numBytes);


Description

Transmits a series of bytes over the I2C interface.

Parameters:

  • source: Segment address of the bytes to transmit.
  • numBytes: The number of bytes to transmit.

Abend Conditions

  • The I2C Slave interface has not been initialised.

miI2CStart


void miI2CStart (void);


Description

Performs a low-level I2C start sequence.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CStop


void miI2CStop (void);


Description

Performs a low-level I2C stop sequence.

Abend Conditions

  • The I2C Master interface has not been initialised.

miI2CTransmitByte


BOOL miI2CTransmitByte (BYTE value);


Description

Transmits a low-level byte over the I2C interface, returning whether an ACK/NACK has been received.

Parameters

  • value: byte to transmit.

Return Calue

  • FALSE = NACK received.
  • TRUE = ACK received.

Abend Conditions

  • The I2C Master interface has not been initialised.

I2C Types

MI_I2C_SLAVE_CONFIG


typedef struct MI_I2C_SLAVE_CONFIG

{

BYTE addressMode;

WORD address;

WORD rxBufferSize;

BYTE rfu;

BYTE frameStartHandlingEnabled;

BYTE clockStretchingEnabled;

BYTE stopOnCollision;

WORD portConfig;

} MI_I2C_SLAVE_CONFIG;


MI_I2C_SLAVE_CONFIG elements:

  • addressMode: This should be set to 0 to select 7-bit addressing. 10-bit addressing may be supported at a later date.
  • address: The I2C slave address.
  • rxBufferSize: The size (in bytes) to be allocated to the Receive Buffer.
  • rfu: reserved for future use.
  • frameStartHandlingEnabled: 1 = 1 enabled; 0 = 0 disabled; For M5-P19 this should always be enabled.
  • clockStretchingEnabled: 1 = enabled; 0 = 0 disabled; It is highly recommended to use clock stretching.
  • stopOnCollision: 1 = enabled; 0 = 0 disabled; Stops data transmission if a collision is detected.
  • portConfig: M5-P19 supports two configurations for I2C in slave mode:
    • 0x0E00: uses GPIO0.4 (SDA) and GPIO0.5(SCL)
    • 0x1400: uses GPIO1.1 (SDA) and GPIO1.0(SCL)

Integrity Checking

Integrity Checking Functions

miPerformIntegrityCheck


void miPerformIntegrityCheck (void);


Description

Performs a system integrity check. MULTOS restarts with an MI_EMBEDDED_EVENT_STARTUP_RESTART_INTEGRITY startup event if the integrity check fails.

Abend Conditions

None.

Printing

Printing Functions

sprintf


WORD sprintf (char *string, char *format, …);


Serial IO

Serial IO Constants

MI_SERIAL_IO_8_BITS_NO_PARITY_1_STOP_BIT

The following serial IO configuration:

  • 8 data bits.
  • No parity bit.
  • 1 stop bits.

MI_SERIAL_IO_NO_PIN

Indicates that no pin is defined.

MI_SERIAL_IO_RECEIVE_BUFFER_EMPTY

The receive buffer is empty.

MI_SERIAL_IO_RECEIVE_BUFFER_FULL

The receive buffer is full but not overflowed.

MI_SERIAL_IO_RECEIVE_BUFFER_NON_EMPTY

The receive buffer is non-empty but not full.

MI_SERIAL_IO_RECEIVE_BUFFER_OVERFLOWED

The receive buffer has overflowed.

Serial IO Functions

miSerialIOFlushReceiveBuffer


void miSerialIOFlushReceiveBuffer (void);


Description

Flushes the receive buffer.

Abend Conditions

  • The serial IO interface has not been initialised.

miSerialIOGetNumReceivedBytes


WORD miSerialIOGetNumReceivedBytes (void);


Description

Returns the number of bytes received over the serial IO interface that are available to read from the receive buffer.

Return Value

The number of bytes received over the serial IO interface.

Abend Conditions

  • The serial IO interface has not been initialised.

miSerialIOGetReceiveBufferState

Protoype


BYTE miSerialIOGetReceiveBufferState (void);


Description

Returns the state of the receive buffer.

Return Value

The state of the receive buffer:

Abend Conditions

  • The serial IO interface has not been initialised.

miSerialIOGetReceivedBytes


WORD miSerialIOGetReceivedBytes (BYTE *dest, WORD maxNumBytes);


Description

Copies bytes from the receive buffer, returning the number of bytes copied.

Parameters

  • dest: the destination area (this must not be in Static).
  • maxNumBytes: the maximum number of bytes to copy.

Abend Conditions

  • The serial IO interface has not been initialised.
  • The destination area is in Static.

miSerialIOInitialise


void miSerialIOInitialise (BYTE txPin, BYTE rxPin, WORD baudRate, BYTE config, WORD rxBufferSize);


Description

Initialises the serial IO interface.

Parameters

  • txPin: the Tx GPIO pin number (0-11). If 255 then the Tx functionality is disabled.
  • rxPin: the Rx GPIO pin number (0-11). If 255 then the Rx functionality is disabled.
  • baudRate: the transmit/receive baud rate.
  • rxBufferSize: the size of the receive buffer in bytes.

Abend Conditions

  • Serial IO port already initialised.
  • Both the Rx an Tx pins have not been allocated.
  • The Rx and Tx pins belong to different GPIO ports.
  • The Rx/Tx pins are already in use.
  • Invalid Rx/Tx pins.
  • Invalid configuration.

Note

  • If both the Rx and Tx pins are specified then they must belong to the same GPIO port.
  • Due to hardware limitations some automatic integrity checks are disabled. For this reason miPerformIntegrityCheck() should be called periodically if the serial IO interface is used.
  • The actual baud rate may not be exactly the same as the specified baud rate due to hardware limitations. If the serial IO interface is not completely reliable then adjust the baud rate value slightly to overcome this limitation. The specified baudRate can be any value and not just one of the standard values (9600, 14400, 19200, 28800, 38400 or 57600 baud).

miSerialIORestrictBuffers


void miSerialIORestrictBuffers (BYTE mode);


Description

Controls whether the serial IO buffers are to be held in Public.

Parameters

  • mode – whether the serial IO buffers are to be held in Public:
    • MI_SERIAL_IO_BUFFERS_UNRESTRICTED – the buffers can be held in Public, the application’s session data or stack, or in Static (if supported).
    • MI_SERIAL_IO_BUFFERS_IN_PUBLIC – the buffers can only be held in Public.

Abend Conditions

  • Invalid mode value.

Notes

If an application calls this function to restrict the buffers to Public and then performs an input/output using buffer that is held in Static or in the application’s session or stack then MULTOS abends for the following serial IO functions.

  • miSerialIOTransmitBytes

    *miSerialIOGetReceivedBytes

Following reset MULTOS allows the buffers to be held in Public, the application’s session data or stack, or in Static and applications must call this primitive to restrict them to Public.

Tip

This function should be used by applications if required to make them more robust against fault attack and application memory dumps.

miSerialIOSetActivePort


void miSerialIOSetActivePort (BYTE port);


Description

Sets the active serial IO port.

Parameters

  • port: the port number.

Abend Conditions

  • The serial IO interface has not been initialised.
  • Invalid port number.

miSerialIOTransmitBytes


void miSerialIOTransmitBytes (BYTE *source, WORD numBytes);


Description

Transmit bytes over the serial interface.

Parameters

  • source: the source area.
  • numBytes: the number of bytes to transmit.

Abend Conditions

  • The serial IO interface has not been initialised.

SPI

SPI Constants

MI_SPI_MODE_MASTER

Master SPI mode.

SPI Functions

miSPIInitialise


void miSPIInitialise (BYTE mode, BYTE numberOfSlaves, WORD *configuration, BOOL enablePullups);


Description

Initialises the SPI interface.

Parameters

  • mode: SPI mode as follows:
  • numberOfSlaves: the number of SPI slave devices (1-8)
  • configuration: pointer to SPI configuration data as follows:
    • Word 0: Slave 1 baud rate and mode
    • Word 1: Slave 2 baud rate and mode
    • etc
  • enablePullups: if TRUE then the internal pullups are enabled for all the SPI output pins

Word 0 and above have the following format:

  • Bits 0-13: the baud rate as follows: baud = fc/(2*(value+1)) where fc is the chip-s internal clock frequency (typically 33MHz). Due to internal timing constraints a too low a value may cause a transmit/receive to fail (hang) or contactless smartcard communication to fail occasionally. Tests have indicated that values of 14 and above work reliably.
  • Bits 14-15: the slave-s mode as follows:
    • 0 (00b): CPOL = 0, CPHA = 0
    • 1 (01b): CPOL = 0, CPHA = 1
    • 2 (10b): CPOL = 1, CPHA = 0
    • 3 (11b): CPOL = 1, CPHA = 1

Abend Conditions

  • The SPI interface is already initialised.
  • Invalid number of slaves (0 or >8).
  • Invalid mode.
  • The specified pins are already in use.

miSPIRestrictBuffers


void miSPIRestrictBuffers (BYTE mode);


Description

Controls whether the SPI buffers are to be held in Public.

Parameters

  • mode – whether the SPI buffers are to be held in Public:
    • MI_SPI_BUFFERS_UNRESTRICTED – the buffers can be held in Public, the application’s session data or stack, or in Static (if supported).
    • MI_SPI_BUFFERS_IN_PUBLIC – the buffers can only be held in Public.

Abend Conditions

  • Invalid mode value.

Notes

If an application calls this function to restrict the buffers to Public and then performs an input/output using buffer that is held in Static or in the application’s session or stack then MULTOS abends for the following SPI functions.

  • miSPITransmitReceive

Following reset MULTOS allows the buffers to be held in Public, the application’s session data or stack, or in Static and applications must call this primitive to restrict them to Public.

Tip

This function should be used by applications if required to make them more robust against fault attack and application memory dumps.

miSPISetSlave


void miSPISetSlave (BYTE slave);


Description

Sets the number of the slave to communicate with.

Parameters

  • slave: the slave number (1 to the number of slaves). If zero then no SS pin is toggled when a transmit/receive is performed.

Abend Conditions

  • The SPI interface has not been initialised.
  • Invalid slave number.

miSPITransmitReceive


void miSPITransmitReceive (BYTE *transmit, BYTE *receive, WORD numBytes, BOOL deselect);


Description

Transmits/receives bytes over the SPI interface.

Parameters

  • transmit: Pointer to the bytes to transmit. If null then no bytes are transmitted (the actual transmitted data is all 0xFFs).
  • receive: Pointer to the area to save the received bytes. If null then the received data is not saved.
  • numBytes: The number of bytes to transmit/receive.
  • deselect:
    • FALSE = don-t deselect the slave at the end of the transaction.
    • TRUE = deselect the slave at the end of the transaction.

Abend Conditions

  • The SPI interface has not been initialised.

Timers

Timer Constants

MI_TIMER_TIME_UNIT_HOURS

Timer units of hours.

MI_TIMER_TIME_UNIT_MILLISECONDS

Timer units of milliseconds.

MI_TIMER_TIME_UNIT_SECONDS

Timer units of seconds.

Timer Functions

miDelay


void miDelay (WORD time);


Description

Performs a delay.

Parameters

  • time: the number of milliseconds to delay.

Abend Conditions

None.

miDelayJitter


void miDelayJitter (WORD time, BYTE jitterPercentage);


Description

Performs a delay with jitter.

Parameters

  • time: the number of milliseconds to delay.
  • jitterPercentage: the amount of time jitter in percent. For example, miDelayJitter (200, 10) would delay for a period 180-220ms.

Abend Conditions

  • jitterPercentage >= 100

miTimerCreate


BYTE miTimerCreate (WORD time, BYTE units);


Description

Creates a new timer.

Parameters

Return value:

The ID of the created timer.

Abend Conditions

  • Unable to create timer.
  • Invalid units.

miTimerExpired


BOOL miTimerExpired (BYTE timerID);


Description

Checks if a given timer has expired.

Parameters

  • timerId: the ID of the timer.

Return Value

  • FALSE = timer not expired.
  • TRUE = timer expired.

Always returns FALSE for count-up timers.

Abend Conditions

  • Invalid timer ID.

miTimerFree


void miTimerFree (BYTE timerID);


Description

Frees a timer.

Parameters

  • timerId: the ID of the timer.

Abend Conditions

  • Invalid timer ID.

miTimerPause


void miTimerPause (BYTE timerID);


Description

Pauses a timer.

Parameters

  • timerId: the ID of the timer.

Abend Conditions

  • Invalid timer ID.

miTimerRead


WORD miTimerRead (BYTE timerID);


Description

Reads the timer value.

Parameters

  • timerId: the ID of the timer.

Return Value

Time current timer value.

Abend Conditions

  • Invalid timer ID.

miTimerResume


void miTimerResume (BYTE timerID);


Description

Resumes a paused timer.

Parameters

  • timerId: the ID of the timer.

Abend Conditions

  • Invalid timer ID.

miTimerStart


void miTimerStart (BYTE timerID);


Description

Starts (or or restarts) a timer.

Parameters

  • timerId: the ID of the timer.

Abend Conditions

  • Invalid timer ID.

miWatchdogInitialise


void miWatchdogInitialise (WORD time, BYTE units);


Description

Initialises the watchdog.

Parameters

  • time: the watchdog time.
  • units: the watchdog time units (must be MI_TIMER_TIME_UNIT_MILLISECONDS).

Abend Conditions

  • Invalid units.

Notes

The watchdog only supports a time of up to 420ms

The watchdog can be reinitialised to different time if required. If the time is specified as 0 then the watchdog is disabled.

miWatchdogRefresh


void miWatchdogRefresh (void);


Description

Refreshes the watchdog.

Abend Conditions

  • Watchdog not initialised.

Version

Version Functions

miGetLibraryVersion


DWORD miGetLibraryVersion (void);


Arithmetic and Logic

multosAdd


void multosAdd (const BYTE blockLength, BYTE *block1, BYTE *block2, BYTE *result)


Parameters

  • const BYTE blockLength: size of the blocks to add.
  • BYTE *block1: address of the first block
  • BYTE *block2: address of the second block
  • BYTE *result: address of the block that will hold the result of the operation

Description

This function adds the value found in block1 to that found in block2 and places the sum in the block indicated in the result parameter. Note that block1, block2 and result are all considered to be of size blockLength.

This is an interface to the instruction ADDN.

multosAnd


void multosAnd (const BYTE blockLength, BYTE *block1, BYTE *block 2, BYTE *result)


Parameters

  • const BYTE blockLength: size of the blocks to add. Both blocks must be the same size.
  • BYTE *block1: address of the first block
  • BYTE *block2: address of the second block
  • const BYTE *result: address of the block that will hold the result of the operation

Description

This function performs a logical using the values found in block1 and block2. The result is written the location given in the result parameter. Note that block1, block2 and result are all considered to be of size blockLength.

This is an interface to the instruction ANDN.

multosBCDtoBIN


BOOL multosBCDtoBIN (BYTE *sourceAddr, BYTE *destAddr, BYTE sourceLen, BYTE destLen);


Parameters

  • BYTE sourceLen: length of data to convert (input)
  • BYTE destLen: length of output buffer pointed to by destAddr (input)
  • BYTE *sourceAddr: pointer to buffer containing the data to convert (input)
  • BYTE *destAddr: pointer to output buffer to hold result of conversion (output)

Description

This function converts between binary coded decimal and binary. It returns TRUE if the conversion is successful.

This is an interface to the primitive Convert BCD.

multosBINtoBCD


BOOL multosBINtoBCD (BYTE *sourceAddr, BYTE *destAddr, BYTE sourceLen, BYTE destLen);


Parameters

  • BYTE sourceLen: length of data to convert (input)
  • BYTE destLen: length of output buffer pointed to by destAddr (input)
  • BYTE *sourceAddr: pointer to buffer containing the data to convert (input)
  • BYTE *destAddr: pointer to output buffer to hold result of conversion (output)

Description

This function converts between binary and binary coded decimal. It returns TRUE if the conversion is successful.

This is an interface to the primitive Convert BCD.

multosCheckBCD


BYTE multosCheckBCD (BYTE *address, BYTE length);


Parameters

  • BYTE length: the length (in bytes) of the block containing the value to be checked
  • BYTE *address: the address of the block containing the value to be checked

Description

The function checks if the provided block contains a valid Binary Coded Decimal value. Retuns 1 if the value is BCD, 0 if not.

This is an interface to the primitive Check BCD.

multosDecrement


void multosBlockDecrement (const BYTE blockLength, const BYTE *block)


Parameters

  • const BYTE blockLength: size of the block on which to perform the operation
  • const BYTE *block: address of the block on which to perform the operation

Description

This function decrements the value held in block by one. This is an interface to the instruction DECN.

multosDivide


void multosDivide (const BYTE blockLength, BYTE *numerator, BYTE *denominator, BYTE *quotient, BYTE *remainder)


Parameters

  • const BYTE blockLength: the size of all operand and result blocks (input)
  • BYTE *numerator: address of the block where the numerator is held (input).
  • BYTE *denominator: address of the block where the denominator is held (input).
  • BYTE *quotient: address of the block where the quotient is to be written (output).
  • BYTE *remainder: address of the block where the remainder is to be written (output).

Description

This function divides the numerator by the denominator. The results of the operation are written to the blocks quotient and remainder.

This is an interface to the primitive DivideN.

multosIncrement


void multosIncrement (const BYTE blockLength, const BYTE *block)


Parameters

  • const BYTE blockLength: size of the block on which to perform the operation
  • const BYTE *block: address of the block on which to perform the operation

Description

This function increments the value held in block by one.

This is an interface to the instruction INCN

multosInvert


void multosInvert (const BYTE blockLength, const BYTE *block)


Parameters

  • const BYTE blockLength: size of the block on which to perform the operation
  • const BYTE *block: address of the block on which to perform the operation

Description

This function logically inverts the value held in block.

This is an interface to the instruction NOTN

multosMultiply


void multosMultiply (const BYTE blockLength, BYTE *block1, BYTE *block2, BYTE *result)


Parameters

  • const BYTE blockLength: the size of the operands
  • BYTE *block1: address of the first byte of block1
  • BYTE *block2: address of the first byte of block2
  • BYTE *result: address of the first byte of result

Description

This function multiplies the value held in block1 by that held in block2 and writes the result to the block result of size blockLength + blockLength.

This is an interface to the primitive MultiplyN.

multosOr


void multosOr (const BYTE blockLength, BYTE *block1, BYTE *block2, BYTE *result)


Parameters

  • const BYTE blockLength: the size of all operand and result blocks
  • BYTE *block1: address of block1
  • BYTE *block2: address of block2
  • BYTE *result: address of the first byte of block where the result is to be written.

Description

This function performs a logical OR operation using the values in block1 and block2 as operands. The output of the operation is written to result.

This is an interface to the instruction ORN.

multosRotateLeft


void multosRotateLeft (BYTE *dataAddr, WORD dataLen, WORD numBits);


Parameters

  • WORD numBits: the number of bits to rotate by
  • WORD dataLen: the length of the data (in bytes) pointed to by data_addr
  • BYTE* dataAddr: the address of the data to be rotated

Description

This function performs bit-wise rotation of the data pointed to dataAddr rotating the bits from most significant (leftmost) to least significant (rightmost).

This is an interface to the primitive Shift Rotate.

multosRotateRight


void multosRotateRight (BYTE *dataAddr, WORD dataLen, WORD numBits);


Parameters

  • WORD numBits: the number of bits to rotate by
  • WORD dataLen: the length of the data (in bytes) pointed to by data_addr
  • BYTE* dataAddr: the address of the data to be rotated

Description

This function performs bit-wise rotation of the data pointed to dataAddr rotating the bits from least significant (rightmost) to most significant (leftmost).

This is an interface to the primitive Shift Rotate.

multosShiftLeft


void multosShiftLeft (BYTE *dataAddr, WORD dataLen, WORD numBits);


Parameters

  • WORD numBits: the number of bits to shift by
  • WORD dataDen: the length of the data (in bytes) pointed to by data_addr
  • BYTE* dataAddr: the address of the data to be shifted

Description

The function performs left shifts on the value found in dataAddr.

This is an interface to the primitive Shift Rotate.

multosShiftRight


void multosShiftRight (BYTE *dataAddr, WORD dataLen, WORD numBits);


Parameters

  • WORD numBits: the number of bits to shift by
  • WORD dataLen: the length of the data (in bytes) pointed to by data_addr
  • BYTE* dataAddr: the address of the data to be shifted

Description

The function performs right shifts on the value found in dataAddr.

This is an interface to the primitive Shift Rotate.

multosSubtract


void multosSubtract (const BYTE blockLength, BYTE *block1, BYTE *block2, const BYTE *result)


Parameters

  • const BYTE blockLength: size of the blocks to subtract. Both blocks must be the same size.
  • BYTE *block1: address of the first block
  • BYTE *block2: address of the second block
  • const BYTE *result: address of the block that will hold the result of the operation

Description

This function subtracts the value found in block1 to that found in block2 and places the difference in the block indicated in result.

This is an interface to the instruction SUBN.

multosSubtractBCD


void multosSubtractBCD (const BYTE length, BYTE *operand1, BYTE *operand2, BYTE *result)


Parameters

  • const BYTE length: the length of each BCD operand (input)
  • BYTE *operand1: address of the first operand (input)
  • BYTE *operand2: address of the second operand (input)
  • BYTE *result: address to hold the result of the subtraction (output)

Description

This function subtracts operand2 from operand1.

This is an interface to the primitive Subtract BCDN.

multosTestZero


void multosTestZero (const BYTE blockLength, const BYTE *block, BOOL *isZero)


Parameters

  • const BYTE blockLength: size of the block to test
  • const BYTE *block: the address of the block to test
  • BOOL *isZero: flag indicating if all bytes are zero

Description

This function tests each byte in block has a value of zero. The flag isZero is set to TRUE if all bytes are zero, otherwise it is set to FALSE.

This is an interface to the instruction TESTN.

multosXor


void multosXor (const BYTE blockLength, BYTE *block1, BYTE *block2, BYTE *reuslt)


Parameters

  • const BYTE blockLength: the size of all operand and result blocks
  • BYTE *block1: address of block1
  • BYTE *block2: address of block2
  • BYTE *result: address of the first byte of block where the result is to be written.

Description

This function performs a logical XOR operation using the values in block1 and block2 as operands. The output pf the operation is written to result.

This is an interface to the instruction XORN.

Program Flow

multosCallCodelet


void multosCallCodelet (BYTE *codeAddress, WORD codeletID);


Parameters

  • WORD codeletID: the unique identifier of the codelet being called
  • BYTE * codeAddress: codelet entry point

Description

This function invokes a codelet and executes the code starting at the entry address.

This is an interface to the primitive Call Codelet.

multosCallExtensionPrimitive


void multosCallExtensionPrimitive (const BYTE extensionNum, const BYTE primTypeLo, const BYTE primTypeHi, const BYTE paramByte)


Parameters

  • const BYTE extensionNum: number indicating the MULTOS implementor
  • const BYTE primTypeLo: least significant byte of the proprietary primitive identifier as allocated by the implementor
  • const BYTE primTypeHi: most significant byte of the proprietary primitive identifier as allocated by the implementor
  • const BYTE paramByte: byte that may be used to pass a parameter to the proprietary primitive

Description

This function calls a proprietary extension primitive.

This is an interface to the primitive Call Extension.

multosCheckCase


BOOL multosCheckCase (BYTE isoCase)


The parameter is a single byte indicating the expected case of the incoming command.

This function (a) instructs the operating system as to how to interpret the APDU received and (b) checks the case of the received command. It returns TRUE if the case is recognised.

This is an interface to the primitive Check Case.

multosDelegate


void multosDelegate (BYTE *aidAddr);


The parameter is a pointer to a buffer containing the AID of the application that will be delegated to. The first byte of the buffer must contain the length of the AID.

This function delegates execution to an application with the given AID.

This is an interface to the primitive Delegate.

multosExit


void multosExit (void);


This function exits the application.

This is an interface to the instruction SYSTEM.

multosExitLa


void multosExitLa (const BYTE la)


The parameter is a single byte value indicating the actual length of response data.

This function exits the application setting La to the value given as la.

This is an interface to the instruction SYSTEM.

multosExitSW


void multosExitSW (const WORD sw)


The parameter is a word value indicating the value of the status word.

This function exits application with status word of sw.

This is an interface to the instruction SYSTEM.

multosExitSWLa


void multosExitSWLa (const WORD sw, const BYTE la)


The paratmeters are:

const WORD sw: a word value indicating the value of the status word

const BYTE la: a single byte value indicating the actual length of response data.

This function exits application with an SW of sw and an La of la.

This is an interface to the instruction SYSTEM.

multosGetDelegatorAID


BOOL multosGetDelegatorAID (const BYTE readBytes, BYTE *aidAddr);


Parameters

  • const BYTE readBytes: length of the AID to fetch (input)
  • BYTE *aidAddr: address where delegator AID is written (output)

Description

This function stores the AID of the delegating application into aidAddr. It returns TRUE if the application has not been delegated to.

This is an interface to the primitive Get Delegator AID.

multosGetProcessEvent


BYTE multosGetProcessEvent (void);


The parameter returns the ID of the event that caused the application to be run. Current events defined in multos.h are:-

EVENT_APP_APDU 0

EVENT_SELECT_APDU 1

EVENT_AUTO_SELECT 2

EVENT_RESELECT_APDU 3

EVENT_DESELECT 4

EVENT_CREATE 5

EVENT_DELETE 6

This is an interface to the primitive Get Process Event.

multosRejectProcessEvent


void multosRejectProcessEvent (void);


This is an interface to the primitive Reject Process Event. See [MDRM] for details of Process Events.

multosRestoreStack


void multosRestoreStack (void);


This function restores the application’s stack to the copy previously saved with multosSaveStack(). The intention of the function is to allow an application to resume execution at the point just after it called multosExitToMultosAndRestart(). It may only be used is specific circumstances. See [MDRM] for details.

This is an interface to the primitive Manage Stack.

multosReturnFromCodelet


void multosReturnFromCodelet (const BYTE numBytesIn, const BYTE numBytesOut);


Parameters

  • const BYTE numBytesIn: the number of stack bytes that were passed to the codelet
  • const BYTE numBytesOut: the number of stack bytes returned by the codelet.

Description

This function returns from the currently executing codelet and ensures that numBytesIn are removed from the stack and numBytesOut replace them.

This is an interface to the primitive Return From Codelet.

multosSaveStack


void multosSaveStack (void);


This function saves the application’s stack to be restored with multosRestoreStack(). The intention of the function is to allow an application to save its execution state at the point just before calling multosExitToMultosAndRestart(). It may only be used is specific circumstances. See [MDRM] for details.

This is an interface to the primitive Manage Stack.

System

multosCardBlock


BOOL multosCardBlock (const BYTE MSB_StartAddress_MAC, const BYTE LSB_StartAddress_MAC);


Parameters

  • const BYTE MSB_StartAddress_MAC: most significant byte of the address of the CBMAC in public memory
  • const BYTE LSB_StartAddress_MAC: least significant byte of the address of the CBMAC in public memory

Description

This function evaluates a card block and blocks the MULTOS device if the is verified (returning TRUE) otherwise it returns FALSE.

This is an interface to the primitive Card Block.

multosCardUnBlock


BOOL multosCardUnBlock (void);


Calls the primitive Card Unblock and returns TRUE if the device is successfully unblocked.

multosGetAID


BYTE multosGetAID (BYTE appNumber, BYTE *dest);


Parameters

  • BYTE appNumber: The number of the application to get the AID of.
  • BYTE *dest: The destination address for the 17-byte AID (one byte length followed by a 16-byte body)

Description

This function provides the AID of the application with the given number (a 1 based index of the loaded applications in the order they are loaded). An application number of zero refers to the executing application.

The function return 0 indicates when an application with the specified application number does not exist and 1 indicates that the application does exist. The AID is only saved in the destination if the application exists.

This is an interface to the Primitive Get AID.

multosGetConfigData


WORD multosGetConfigData (WORD token, BYTE* outAddr);


Parameters

  • WORD token: A two byte value containing the P1 P2 values defined for the Get Configuration Data APDU command (see [MDRM]).
  • BYTE* outAddr: Points to a buffer to contain the requested configuration data.

Description

Example:

dataLen = multosGetConfigData(0x0200,outAddr);

Returns the number of bytes written to outAddr or zero if an error condition occurred.

This is an interface to the primitive Get Configuration Data.

multosGetData


BYTE multosGetData (const BYTE readLength, BYTE *outAddr);


Parameters

  • const BYTE readLength: the maximum number of bytes to read – should correspond with the size of the output buffer (input)
  • BYTE *outAddr: pointer to a buffer to hold the output of the function. (output)

Description

Returns the actual number of bytes written to the output buffer.

This is an interface to the primitive Get Data.

multosGetDIRFile


BYTE multosGetDIRFile (const BYTE readLength, BYTE recNo, BYTE *addr);


Parameters

  • const BYTE readLength: the number of bytes of the DIR record to copy (input)
  • BYTE recNo: DIR record number (input)
  • BYTE *addr: address where result is written (output)

Description

This function retrieves the record recNo from the DIR File and copies it to addr. It returns the actual number of bytes copied.

Note: recNo is a 1 based index. A value of 0 indicates the currently selected application.

This is an interface to the primitive Get DIR File Record.

multosGetFCI


BYTE multosGetFCI (const BYTE readLength, BYTE recNo, BYTE *addr);


Parameters

  • const BYTE readLength: the number of bytes of the FCI record to copy (input)
  • BYTE recNo: FCI record number (input)
  • BYTE *addr: address where result is written (output)

Description

This function retrieves the File Control Information for the application with index recNo and copies it to addr. It returns the actual number of bytes copied.

Note: recNo is a 1 based index. A value of 0 indicates the currently selected application.

This is an interface to the primitive Get File Control Information.

multosGetFCIState


BYTE multosGetFCIState();


This function returns 1 if the executing application has a dual FCI or 0 if it has a normal FCI.

This is an interface to the primitive Get FCI State.

multosGetManufacturerData


BYTE multosGetManufacturerData (const BYTE readLength, BYTE *addr);


Parameters

  • const BYTE readLength: the number of bytes to be copied (input)
  • BYTE *addr: address where result is written (output)

Description

This function retrieves the Manufacturer Data from MULTOS chip and writes the result to addr. It also returns the actual number of bytes copied.

This is an interface to the primitive Get Manufacturer Data.

multosGetMultosData


BYTE multosGetMultosData (const BYTE readLength, BYTE *addr);


Parameters

  • const BYTE readLength: the number of bytes to be copied (input)
  • BYTE *addr: address where result is written (output)

Description

This function retrieves the MULTOS Data from MULTOS chip and writes it to output. It also returns the actual number of bytes copied.

This is an interface to the primitive Get MULTOS Data.

multosQueryCodelet


BOOL multosQueryCodelet (WORD codeletID);


This function verifies the existence of a specific codelet with ID codeletID and returns TRUE if it is supported.

This is an interface to the primitive Query Codelet.

multosQueryCryptographicAlgorithm


BOOL multosQueryCryptographicAlgorithm (BYTE algorithmID);


Returns TRUE if the algorithm is supported by the device.

This is an interface to the primitive Query Cryptographic Algorithm. See [MDRM] for the valid values of algorithmId.

multosQueryPrimitive


void multosQueryPrimitive (const BYTE setNum, const BYTE primitiveNum, BOOL *primitiveSupported)


Parameters

  • const BYTE setNum: the set to which the primitive belongs
  • const BYTE primitiveNum: the number of the primitive within its set
  • BOOL *primitiveSupported: Boolean flag

Description

This function verifies the existence of a specific primitive with number primitiveNum within set setNum. The flag primitiveSupported is set to TRUE if the primitive is supported, otherwise it is set to FALSE.

This is an interface to the primitive Query Primitive.

Cryptography

multosChecksum


DWORD multosChecksum (BYTE *blockAddr, WORD length);


Parameters

  • WORD length: the length of the block to use as input to the checksum algorithm
  • BYTE *blockAddr: the address of the first byte of the input block

Description

The function generates a four-byte checksum of the data block.

This is an interface to the primitive Checksum.

multosDecipherCBC


void multosDecipherCBC (const BYTE algo, BYTE *inputAddr, BYTE *outputAddr, BYTE keyLen, BYTE *keyAddr, WORD inputLen, BYTE *ivAddr, BYTE ivLen);


Parameters

  • const BYTE algo: 0x03 = DES, 0x04 = 3DES, 0x05 = SEED, 0x06 = AES (input)
  • WORD inputLength: Length of cipher text (input)
  • BYTE *inputAddr: pointer to cipher text to decipher (input)
  • BYTE *outputAddr: pointer to memory in which to write the plain text output. (output)
  • BYTE ivLen: length of the Initial Chaining Vector pointed to by ivAddr (input)
  • BYTE *ivAddr: Pointer to ICV value (input)
  • BYTE keyLen: length of key, depends on algorithm being used (input)
  • BYTE *keyAddr: pointer to the key to use (input)

Description

This function deciphers the cipher text using the cipher block chaining method and supports a number of algorithms.

This is an interface to the primitive Block Decipher.

multosDecipherECB


void multosDecipherECB (const BYTE algo, BYTE *inputAddr, BYTE *outputAddr, BYTE keyLen, BYTE *keyAddr, WORD inputLen);


Parameters

  • const BYTE algo: 0x03 = DES, 0x04 = 3DES, 0x05 = SEED, 0x06 = AES (input)
  • WORD inputLen: Length of cipher text (input)
  • BYTE *inputAddr: pointer to cipher text to decipher (input)
  • BYTE *outputAddr: pointer to memory in which to write the plain text output. (output)
  • BYTE keyLen: length of key, depends on algorithm being used (input)
  • BYTE *keyAddr: pointer to the key to use (input)

Description

This function deciphers the cipher text using the electronic code book method and supports a number of algorithms.

This is an interface to the primitive Block Decipher.

multosEccGenerateKeyPair


BOOL multosEccGenerateKeyPair (BYTE *keyAddr, BYTE *domainAddr);


Parameters

  • BYTE *keyAddr: address of buffer (size = 3 x prime length) to hold generated key pair (output)
  • BYTE *domainAddr: address of domain parameters structure (input)

Description

This generates and ECC key pair for the given domain parameters. The domain parameter structure is described in [MDRM]. The function returns TRUE if a key pair was successfully generated. A version of this function, multosEccGenerateKeyPairProtected, internally encrypts the private key.

This is an interface to the primitive ECC Generate Key Pair.

multosECDH


BOOL multosECDH (BYTE *sharedAddr, BYTE *publicKeyAddr, BYTE *privateKeyAddr, BYTE *domainAddr);


Parameters

  • BYTE *domainAddr: address of domain parameters structure (input)
  • BYTE *privateKeyAddr: private part of key A (input)
  • BYTE *publicKeyAddr: public part of key B (input)
  • BYTE *sharedAddr: address of buffer to store computed shared secret key (output)

Description

Computes a shared key using a private key and a public key belonging to another key-pair. If the private key is protected (i.e. created using multosEccGenerateKeyPairProtected) then the function multosECDHProtected must be used instead. Both functions return TRUE if the shared key was successfully calculated.

This is an interface to the primitive ECC Elliptic Curve Diffie Hellman.

multosECDSA


BOOL multosECDSA (BYTE *sigAddr, BYTE *hashAddr, BYTE *privateKeyAddr, BYTE *domainAddr);


Parameters

  • BYTE *domainAddr: address of domain parameters structure (input)
  • BYTE *privateKeyAddr: address of the private key to use for signing (input)
  • BYTE *hashAddr: address of the hash to sign (input)
  • BYTE *sigAddr: address of buffer to hold the signature (output)

Description

This performs an Elliptic Curve Digital Signature Algorithm signature of the hash data provided. The buffer pointed to by sigAddr must be twice the key’s prime length. If the private key is protected (i.e. created using multosEccGenerateKeyPairProtected) then the function multosECDSAProtected must be used instead. Both functions return TRUE if the signature was successfully calculated.

This is an interface to the primitive ECC Generate Signature.

multosECDSAVerify


BOOL multosECDSAVerify (BYTE *hashAddr, BYTE *sigAddr, BYTE *publicKeyAddr, BYTE *domainAddr);


Parameters

  • BYTE *domainAddr: address of domain parameters structure (input)
  • BYTE *hashAddr: address of the hash to compare (input)
  • BYTE *sigAddr: address of the signature to decrypt and compare to the given hash (input)
  • BYTE *publicKeyAddr: address of the public key to use to decrypt the signature (input)

Description

The function returns TRUE if the signature was validated.

This is an interface to the primitive ECC Verify Signature.

multosEncipherCBC


void multosEncipherCBC (const BYTE algo, BYTE *inputAddr, BYTE *outputAddr, BYTE keyLen, BYTE *keyAddr, WORD inputLen, BYTE *ivAddr, BYTE ivLen);


Parameters

  • const BYTE algo: 0x03 = DES, 0x04 = 3DES, 0x05 = SEED, 0x06 = AES (input)
  • WORD inputLength: Length of plain text (input)
  • BYTE *inputAddr: pointer to plain text to encipher (input)
  • BYTE *outputAddr: pointer to memory in which to write the cipher text output. (output)
  • BYTE ivLen: length of the Initial Chaining Vector pointed to by ivAddr (input)
  • BYTE *ivAddr: Pointer to ICV value (input)
  • BYTE keyLen: length of key, depends on algorithm being used (input)
  • BYTE *keyAddr: pointer to the key to use (input)

Description

This function enciphers the plain text using the cipher block chaining method and supports a number of algorithms.

This is an interface to the primitive Block Encipher.

multosEncipherECB


void multosEncipherECB (const BYTE algo, BYTE *inputAddr, BYTE *outputAddr, BYTE keyLen, BYTE *keyAddr, WORD inputLen);


Parameters

  • const BYTE algo: 0x03 = DES, 0x04 = 3DES, 0x05 = SEED, 0x06 = AES (input)
  • WORD inputLen: Length of plainText (input)
  • BYTE *inputAddr: pointer to plain text to encipher (input)
  • BYTE *outputAddr: pointer to memory in which to write the cipher text output. (output)
  • BYTE keyLen: length of key, depends on algorithm being used (input)
  • BYTE *keyAddr: pointer to the key to use (input)

Description

This function enciphers the plain text using the electronic code book method and supports a number of algorithms.

This is an interface to the primitive Block Encipher.

multosGenerateDESCBCSignature


void multosGenerateDESCBCSignature (BYTE *inputAddr, BYTE *sigAddr, BYTE *keyAddr, BYTE *ivAddr, WORD length);


Parameters

  • WORD length: the length of the input data (input)
  • BYTE *inputAddr: the address of the input data (input)
  • BYTE *ivAddr: initial value to use in algorithm [8 bytes] (input)
  • BYTE *keyAddr: key to use [8 bytes] (input)
  • BYTE *signAddr: array to hold 8-byte signature (output)

Description

This function generates an eight byte Signature over the input data.

This is an interface to the primitive Generate Signature.

multosGenerateMAC


void multosGenerateMAC (const BYTE algorithm, BYTE *inputAddr, BYTE *MACAddr, BYTE *keyAddr, BYTE *IVAddr, WORD length, BYTE paddingByte);


Parameters

  • const BYTE algorithm: Specifies the MAC algorithm to use. For supported algorithms see [MDRM].
  • BYTE *inputAddr: address of the data to be MAC’d
  • BYTE *MACAddr: address of the buffer to hold the resulting MAC
  • BYTE *keyAddr: address of the key to use to generate the MAC
  • BYTE *IVAddr: address of the initialisation vector for the MAC algorithm
  • WORD length: length of the input data in bytes
  • BYTE paddingByte: the value of the padding byte to use

Description

This is an interface to the primitive Generate MAC.

multosGenerateRsaKeyPair


BOOL multosGenerateRsaKeyPair (const BYTE method, const BYTE mode, WORD mLen, BYTE *mAddr, BYTE *dpdqpquAddr, BYTE *eAddr, WORD eLen, WORD keyLen);


Parameters

  • const BYTE method: Generation method, 0x00 = default, 0x01 = X9.31 (input)
  • const BYTE mode: Default gen mode, 0x00 = performance, 0x01 = balanced, 0x02 = confidence (input)
  • WORD keyLen: required length, in bytes, of the key pair public modulus (input)
  • WORD eLen: length, in bytes, of the given exponent (input)
  • BYTE* eAddr: address of the exponent value to use (input)
  • BYTE* dpdqpquAddr: address of buffer to hold generated CRT private key (output)
  • BYTE* mAddr: address of buffer to hold the generated public modulus (output)
  • WORD mLen: equal to keyLen or 0 if the modulus is not to be returned (input)

Description

Returns TRUE if the command is successful.

This is an interface to the primitive Generate RSA Key Pair.

multosGenerateTripleDESCBCSignature


void multosGenerateTripleDESCBCSignature (BYTE *inputAddr, BYTE *sigAddr, BYTE *keyAddr, BYTE *ivAddr, WORD length);


Parameters

  • WORD length: the length of the input data (input)
  • BYTE *inputAddr: the address of the input data (input)
  • BYTE *ivAddr: initial 8 byte value to use in Triple algorithm (input)
  • BYTE *keyAddr: 16 byte key to use (input)
  • BYTE *sigAddr: array to hold 8-byte signature (output)

Description

This function generates an eight byte Triple Signature.

This is an interface to the primitive Generate Triple Signature.

multosGetRandomNumber


QWORD multosGetRandomNumber (void);


This function generates an 8-byte random number.

This is an interface to the primitive Get Random Number.

multosModularExponentiation


void multosModularExponentiation (BYTE *outAddr, BYTE *inAddr, BYTE *mAddr, BYTE *eAddr, WORD mLen, WORD eLen);


Parameters

  • WORD eLen: the length of the exponent used (input)
  • WORD mLen: the length of the modulus (input)
  • BYTE *eAddr: address of the exponent (input)
  • BYTE *mAddr: address of the modulus (input)
  • BYTE *inAddr: address of the input value (input)
  • BYTE *outAddr: address of where to write the result of the operation (output)

Description

This function performs a modular exponentiation. Note that the values held at mAddr, inAddr and outAddr are all considered to be of size mLen.

This is an interface to the primitive Modular Exponentiation.

multosModularExponentiationCRT


void multosModularExponentiationCRT (BYTE *outAddr, BYTE *inAddr, BYTE *pquAddr, BYTE *dpdqAddr, WORD dpdqLen);


Parameters

  • WORD dpdqLen: length of dpdq (input)
  • BYTE *dpdqAddr: address of dpdq (input)
  • BYTE *pquAddr: address of pqu (input)
  • BYTE *inAddr: address of input (input)
  • BYTE *outAddr: address of output (output)

Description

This function performs a modular exponentiation using Chinese Remainder Theorem.

This is an interface to the primitive Modular Exponentiation .

Note: A version of this function, multosModularExponentiationCRTProtected, exists with the same prototype that interfaces to the primitive Modular Exponentiation CRT Protected instead.

multosPad


WORD multosPad (const BYTE scheme, BYTE *addrMsg, WORD lenMsg, BYTE blockLen);


Parameters

  • WORD lenMsg: the length of data pointed to by msg (input)
  • BYTE *addrMsg: address of the data to be padded (input/output)
  • BYTE blockLen: size in bytes of the block length to pad to (input)
  • BYTE scheme: (const input)

Description

0x01 = 0x80 followed by zero or more 0x00

0x02 = 0x80 followed by one or more 0x00

This uses the primitive Pad to pad a message to a given block length using one of the two methods specified. Returns the length of the padded message.

multosPlatformOptimisedChecksum


DWORD multosPlatformOptimisedChecksum (BYTE *blockAddr, WORD length);


Parameters

  • WORD length: length of the data to calculate the checksum over
  • BYTE *blockAddr: pointer to the data to calculate the checksum over

Description

This function calls the primitive Platform Optimised Checksum to return an implementation specific 4 byte checksum.

multosRsaVerify


void multosRsaVerify (BYTE *outAddr, BYTE *inAddr, BYTE *mAddr, BYTE *eAddr, WORD mLen, WORD eLen);


Parameters

  • WORD eLen: length of the exponent value pointed to by eAddr. (input)
  • WORD mLen: length of the public modulus pointed to by mAddr. (input)
  • BYTE *eAddr: buffer holding the exponent value (input)
  • BYTE *mAddr: buffer holding the public modulus (input)
  • BYTE *inAddr: buffer holding the input to the modular exponentiation operation (input)
  • BYTE *outAddr: buffer for the result of the modulus exponentiation operation (output)

Description

This primitive performs modular exponentiation operation and the result is written at the specified address outAddr.

This is an interface to the primitive RSA Verify.

multosSecureHash


void multosSecureHash (BYTE *addrMsg, BYTE *addrHash, WORD lenHash, WORD lenMsg);


Parameters

  • WORD lenMsg: length of the data pointed to by msgIn (input)
  • WORD lenHash: length of the required hash value (input)
  • BYTE *addrHash: address of buffer to hold hash result (output)
  • BYTE *addrMsg: address of the message to hash (input)

Description

This is an interface to the primitive Secure Hash and supports SHA-1 and SHA-2 digests of various lengths as documented in the [MDRM].

multosSecureHashIV


void multosSecureHashIV (WORD msgLen, WORD hashLen, BYTE *hashOut, BYTE *msgIn, BYTE *intermediateHash, DWORD *numPrevHashedBytes, WORD *numMsgRemainder, WORD *msgRemainder);


Parameters

  • WORD msgLen: The size, in bytes, of msgIn (input)
  • WORD hashLen: The length of the required hash, in bytes (input)
  • BYTE *hashOut: Address of buffer to hold the resulting hash (output)
  • BYTE *msgIn: Address of the message to hash (input)
  • BYTE *intermediateHash: Address of initialisation vector to input to the hash (input)
  • DWORD *numPrevHashedBytes: Address of count of number of bytes previously input to the hashing algorithm (input/output)
  • WORD *numMsgRemainder: Number of non block aligned bytes (input/output)
  • WORD *msgRemainder: Non block-aligned bytes (input/output)

Description

This is an interface to the primitive Secure Hash IV.

multosSHA1


void multosSHA1 (BYTE *addrMsg, BYTE *addrHash, WORD lenMsg);


Parameters

  • WORD lenMsg: length of the message to submit to the SHA-1 algorithm (input)
  • BYTE *addrMessage: address of the message (input)
  • BYTE *addrHash: address where to write the 20-byte digest (output)

Description

This function uses the value found in addrMessage of size lenMsg as input to the SHA-1 hashing algorithm. The resulting 20-byte digest is written to addrHash.

This is an interface to the primitive SHA-1.

multosUnPad


WORD multosUnPad (const BYTE scheme, BYTE *addrMsg, WORD lenMsg);


Parameters

  • WORD lenMsg: the length of data pointed to by addrMsg (input)
  • BYTE *addrMsg: address of the data to have the padding removed (input/output)
  • BYTE scheme: (const input)

Description

0x01 = 0x80 followed by zero or more 0x00

0x02 = 0x80 followed by one or more 0x00

Memory

multosClear


void multosClear (const BYTE blockLength, const BYTE *block)


Parameters

  • const BYTE blockLength: size of the block to clear
  • const BYTE *block: address of the block to be cleared

Description

This function sets the value of each byte of the block of size blockLength to zero.

This is an interface to the instruction CLEARN.

multosCompare


BYTE multosCompare (BYTE *addr2, BYTE *addr1, WORD length);


Parameters

  • WORD length: size of the blocks to be compared. Both blocks must be the same size.
  • BYTE *addr1: address of the first block
  • BYTE *addr2: address of the second block

Description

This function compares block1 and block2, returns one of the following results:

MULTOS_BLOCK1_GT_BLOCK1

MULTOS_BLOCK2_GT_BLOCK1

MULTOS_BLOCK1_EQ_BLOCK2

Note that the blocks at addr1 and addr2 are considered to be of size blockLength.

This is an interface to the primitive Memory Compare.

Note: The function multosCompareFixedLength (const BYTE length, BYTE* addr2, BYTE* addr1) also exists but uses the primitive Memory Compare Fixed Length instead.

multosCompareEnhanced


WORD multosCompareEnhanced (const BYTE mode, BYTE *addr2, BYTE *addr1, WORD length);


Parameters

  • const BYTE mode: 0 = equality only test, 1 = equality and greater/less than test
  • WORD length: size of the blocks to be compared. Both blocks must be the same size.
  • BYTE *addr1: address of the first block
  • BYTE *addr2: address of the second block

Description

Equality Only Test

The two memory areas are tested for equality and the function can return one of the following values:-

0x5555 = blocks not equal

0xAAAA = blocks equal

Equality and Greater/Less Than Test

The comparison is based on subtraction and the function can return one of the following values:-

0x5A5A = byte block at addr1 > byte block at addr2

0xA5A5 = byte block at addr1 < byte block at addr2

0xAAAA = blocks equal

This is an interface to the primitive Memory Compare Enhanced.

multosCopy


void multosCopy (BYTE *sourceAddr, BYTE *destAddr, WORD length);


Parameters

  • WORD length: the size of the block to copy
  • BYTE *sourceAddr: address of the source block
  • BYTE *destAddr: address of the destination block

Description

This function copies data of size length from sourceAddr to destAddr.

This is an interface to the primitive Memory Copy.

Note 1: multosCopyNonAtomic performs a non-atomic copy. See [MDRM] for details and a definition of non-atomic memory operations.

multosCopyFixedLength


void multosCopyFixedLength (const BYTE length, BYTE *sourceAddr, BYTE *destAddr);


Parameters

  • BYTE length: the size of the block to copy
  • BYTE *sourceAddr: address of the source block
  • BYTE *destAddr: address of the destination block

Description

This function copies data of size length from sourceAddr to destAddr.

This is an interface to the primitive Memory Copy Fixed Length.

Note 1: multosCopyFixedLengthNonAtomic performs a non-atomic copy. See [MDRM] for details and a definition of non-atomic memory operations.

multosCopyFromAdditionalStatic


void multosCopyFromAdditionalStatic (DWORD staticOffset, BYTE *segAddr, WORD length);


Parameters

  • BYTE *segAddr: address in “normal” static to copy to (input)
  • DWORD staticOffset: the offset in “additional” static* to copy from (input)
  • WORD length: the number of bytes to copy (input)

Description

This copies a block of bytes from Additional Static memory to a location in the normal Static memory segment. A version of this function, multosCopyFromAdditionalStaticAtomic, with the same parameters, performs an atomic copy.

* Note: “additional” static memory is contiguous with “normal” static memory and shares the same base address. However, “additional” static may extend beyond 64K bytes so cannot be addressed with a normal 2 byte address.

This is an interface to the primitive Memory Copy Additional Static.

multosCopySessionFromReplacedApp


void multosCopySessionFromReplacedApp (WORD sessionOffset, BYTE *segAddr, WORD length);


Parameters

  • WORD sessionOffset: An offset into the session memory of the application being replaced.
  • BYTE *segAddr: The destination to copy the memory to.
  • WORD length: The length of data to copy.

Description

This function allows for the currently executing application to copy the Session data belonging to the application that it is replacing. It can only be called when an application is being called as part of an application replacement event. This can be determined by calling multosGetReplacedAppState().

The copy function is non-atomic. For an atomic copy, use multosCopySessionFromReplacedAppAtomic() which has identical parameters.

This is an interface to the primitive Memory Copy From Replaced Application.

multosCopyStaticFromReplacedApp


void multosCopyStaticFromReplacedApp (DWORD staticOffset, BYTE *segAddr, WORD length);


Parameters

  • DWORD staticOffset: An offset into the static memory of the application being replaced.
  • BYTE *segAddr: The destination to copy the memory to.
  • WORD length: The length of data to copy.

Description

This function allows for the currently executing application to copy the Static data belonging to the application that it is replacing. It can only be called when an application is being called as part of an application replacement event. This can be determined by calling multosGetReplacedAppState().

The copy function is non-atomic. For an atomic copy, use multosCopyStaticFromReplacedAppAtomic() which has identical parameters.

This is an interface to the primitive Memory Copy From Replaced Application.

multosCopyToAdditionalStatic


void multosCopyToAdditionalStatic (BYTE *segAddr, DWORD staticOffset, WORD length);


Parameters

  • BYTE *segAddr: address in “normal” static to copy from (input)
  • DWORD staticOffset: the offset in “additional” static* to copy to (input)
  • WORD length: the number of bytes to copy (input)

Description

This copies a block of bytes from normal Static memory to Additional Static memory. A version of this function, multosCopyToAdditionalStaticAtomic, with the same parameters, performs an atomic copy.

* Note: “additional” static memory is contiguous with “normal” static memory and shares the same base address. However, “additional” static may extend beyond 64K bytes so cannot be addressed with a normal 2 byte address.

This is an interface to the primitive Memory Copy Additional Static.

multosCopyWithinAdditionalStatic


void multosCopyWithinAdditionalStatic (DWORD srcOffset, DWORD destOffset, DWORD length);


Parameters

  • DWORD destOffset: the offset in “additional” static* to copy to (input)
  • DWORD srcOffset: the offset in “additional” static* to copy (input)
  • DWORD length: the number of bytes to copy (input)

Description

This function copies a block of bytes from one location in Additional Static memory to another. A version of this function, multosCopyWithinAdditionalStaticAtomic, with the same parameters, performs an atomic copy.

* Note: “additional” static memory is contiguous with “normal” static memory and shares the same base address. However, “additional” static may extend beyond 64K bytes so cannot be addressed with a normal 2 byte address.

This is an interface to the primitive Memory Copy Additional Static.

multosFillAdditionalStatic


void multosFillAdditionalStatic (DWORD staticOffset, DWORD length, BYTE value);


Parameters

  • DWORD staticOffset: starting address in “additional” static to fill (input)
  • BYTE value: the value to fill “additional” static with (input)
  • DWORD length: the number of bytes to fill (input)

Description

This fills a block of memory in Additional Static with the given value. This can also be performed as an atomic operation using the function multosFillAdditionalStaticAtomic.

This is an interface to the primitive Memory Fill Additional Static.

multosGetReplacedAppState


BYTE multosGetReplacedAppState (void);


This function returns

• 0 = No replaced application exists

• 1 = Replaced application exists but is not readable (bit 13 of its access_list is not set)

• 2 = Replaced application exists and is readable (bit 13 of its access_list is set)

This is an interface to the primitive Get Replaced Application State.

multosGetSessionSize


WORD multosGetSessionSize (void);


Returns the current size of the executing application’s Session data. It is an interface to the primitive Get Session Size.

multosGetStaticSize


BOOL multosGetStaticSize ( DWORD* value );


Parameters

  • DWORD *value: amount of static memory allocated (output)

Description

Returns TRUE if the command is successful.

This calls the primitive Get Static Size to return the amount of static memory allocated by the OPEN MEL APPLICATION command which includes “normal” static memory included in the ALU and “additional” static memory that is accessed using the Additional Static primitives.

multosGetTransactionState


BYTE multosGetTransactionState (void);


The function returns 1 if transaction protection is on and 0 if it is off.

This is an interface to the primitive Get Transaction State.

multosIndex


void multosIndex (BYTE blockLength, BYTE index, BYTE *baseAddr, BYTE *resultData)


Parameters

  • BYTE blockLength: the length of records in the file (input)
  • BYTE index: the index of the record to be retrieved (input)
  • BYTE *baseAddr: the address of the first byte of the file (input)
  • BYTE *resultData: a pointer to the memory to hold blockLength number of bytes output.

Description

This is an interface to the instruction Index.

multosLookup


BOOL multosLookup (BYTE *arrayAddr, BYTE value, BYTE *resultOffset);


Parameters

  • BYTE value: the value to locate
  • BYTE *arrayAddr: address of the array to be searched.
  • BYTE *resultOffset: address of the byte to which the result will be written

Description

This function locates the first occurrence of value within the search array. Note that this function treats the first byte of the array as indicating the total number of bytes in the array. The function returns TRUE if value is found and resultOffset is the offset within the array where value is first found.

This is an interface to the primitive Lookup.

multosLookupWord


BYTE multosLookupWord (WORD *arrayAddr, WORD value, WORD *resultOffset);


Parameters

  • WORD value: the value to locate
  • WORD *block: address of the word array to be searched.
  • WORD *result: address to which the result will be written
  • BOOL *wordFound: true if the value is found

Description

This function locates the first occurrence of value within the array. Note that this function treats the first word of the array as indicating the total number of words in the array. The function returns the following values:

9: full match,

8: MSB of value matches,

1: LSB of value matches.

resultOffset is the offset within the array where value is first found.

This is an interface to the primitive Lookup Word.

multosResetSessionData


void multosResetSessionData (void);


This function allows a shell application to reset the session data of all other applications on the MULTOS card.

This is an interface to the primitive Reset Session Data.

multosSetProtectedMemoryAccess


void multosSetProtectedMemoryAccess (const BYTE options);


Parameters

  • const BYTE options: Options value to set

Description

options is either 0x00 for off, or 0x01 for on. This is an interface to the Set Protected Memory Access primitive.

multosSetTransactionProtection


void multosSetTransactionProtection (const BYTE options);


Parameters

  • const BYTE options: option value to set

Description

The parameter is a byte value specifying what option to use with transaction protection.

The only valid options are the following:

MULTOS_TP_OFF__DISCARD

MULTOS_TP_OFF__COMMIT

MULTOS_TP_ON__DISCARD

MULTOS_TP_ON__COMMIT

This is an interface to the primitive Set Transaction Protection.

multosUpdateSessionSize


BYTE multosUpdateSessionSize (WORD sessionSize);


This primitive updates the total size of the application’s session memory allowing you to free up space no longer required or allocate more space if needed (up to the maximum allowed in the ALC and available remaining RAM). Returns 1 if the operation succeeds or 0 if it fails.

This is an interface to the primitive Update Session Size.

multosUpdateStaticSize


BYTE multosUpdateStaticSize (DWORD staticSize);


This primitive updates the total size of the application’s Static memory allowing you to free up space no longer required or allocate more space if needed (up to the maximum allowed in the ALC and available remaining space). Returns 1 if the operation succeeds or 0 if it fails.

This is an interface to the primitive Update Static Size.

PIN Management

multosGetPINStatus


BYTE multosGetPINStatus (void);


Returns the PIN status value as defined in the [MDRM].

This is an interface to the primitive Get PIN Data.

multosGetPINTryCounter


BYTE multosGetPINTryCounter (void);


The parameter returns the current PIN Try Counter value.

This is an interface to the primitive Get PIN Data.

multosGetPINTryLimit


BYTE multosGetPINTryLimit (void);


The parameter returns the current PIN Try Limit value.

This is an interface to the primitive Get PIN Data.

multosInitialisePIN


void multosInitialisePIN (BYTE *initDataAddr);


The parameter is a pointer to a data block containing the PIN initialisation data formatted as follows:

PIN Reference Data (8 bytes)

PIN Length (1 byte)

PIN Try Counter (1 byte)

PIN Try Limit (1 byte)

Checksum (4 bytes)

This is an interface to the primitive Initialise PIN.

multosInitialisePINExtended


void multosInitialisePINExtended (BYTE *initDataAddr);


The parameter is a pointer to a data block containing the PIN initialisation data formatted as follows:

PIN Length (1 byte)

PIN Reference Data (PIN Length bytes)

PIN Try Counter (1 byte)

PIN Try Limit (1 byte)

Checksum (4 bytes)

This is an interface to the primitive Initialise PIN Extended.

multosGetPINVerificationStatus


BYTE multosGetPINVerificationStatus (void);


The function returns 0xA5 if the PIN is verified and 0x5A if unverified.

This is an interface to the primitive Get PIN Data.

multosReadPIN


BYTE multosReadPIN (BYTE *outAddr);


The parameters points to a buffer to hold the returned PIN. The function returns the length of the PIN.

This is an interface to the primitive Read PIN.

multosSetPINTryCounter


void multosSetPINTryCounter (BYTE value);


Parameters

  • BYTE value: Counter value to set

Description

Sets the current PIN Try Counter to the value given.

This is an interface to the primitive Set PIN Data.

multosSetPINTryLimit


void multosSetPINTryLimit (BYTE value);


Parameters

  • BYTE value: PIN try limit value to set

Description

Sets the current PIN Try Limit to the value given.

This is an interface to the primitive Set PIN Data.

This uses the primitive Unpad to remove the padding from a message and returns the length of the unpadded message.

multosSetPINVerificationStatus


void multosSetPINVerificationStatus (BYTE value);


Sets the current PIN Verification Status to the value given. The value must be 0x5A (unverified) or 0xA5 (verified).

This is an interface to the primitive Set PIN Data.

multosVerifyPIN


WORD multosVerifyPIN (BYTE *pinAddr, BYTE pinLen);


Parameters

  • BYTE pinLen: Length of the PIN held in the given buffer (input)
  • BYTE *pinAddr: Pointer to the buffer holding the PIN (input)

Description

This function returns the result of the verification process. 0x5AA5 for verified, 0xA55A for NOT verified.

This is an interface to the primitive Verify PIN.