API Reference
Trust Anchor Specific API
Include file: <mi.h> | Linker switch: -lmi
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)
C Language Support
|
ctype.h isalpha stdio.h printf** |
stdlib.h abs heap.h heap_init |
string.h memcpy |
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.
A GPIO embedded event – a monitored GPIO pin has changed state.
An I2C slave embedded event – an event has occurred over the slave I2C interface.
Not an embedded event – the event is a smartcard event.
A serial IO embedded event – a monitored serial channel event has occurred.
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.
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.
Embedded Event Functions
miDeregisterEmbeddedEvent
void miDeregisterEmbeddedEvent (BYTE eventId, BYTE eventInfo);
Description
Deregisters the application to the specified embedded event.
Parameters
- eventId: the ID of the embedded event – one of:
- eventInfo: the information associated with the embedded event. This depends upon the event ID as follows:
- MI_EMBEDDED_EVENT_TIMER – the timer ID.
- MI_EMBEDDED_EVENT_GPIO – the GPIO port.
- MI_EMBEDDED_EVENT_SERIAL_IO – the serial IO port number (bits 0-1).
- MI_EMBEDDED_EVENT_I2C_SLAVE – The I2C event does not have any event info associated with it.
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
- eventId: the embedded event to flush – one of:
Abend Conditions
None.
miFlushEmbeddedEventWithInfo
void miFlushEmbeddedEventWithInfo (BYTE eventId, BYTE eventInfo);
Description
Flushes an event/info combination from the event queue.
Parameters
- eventId: the embedded event to flush – one of:
- eventInfo: the embedded event information to flush. This depends on the event ID as follows:
- MI_EMBEDDED_EVENT_STARTUP – one of:
- MI_EMBEDDED_EVENT_TIMER – the timer ID.
- MI_EMBEDDED_EVENT_GPIO – the GPIO port number.
- MI_EMBEDDED_EVENT_SERIAL_IO – the serial IO port number.
Abend Conditions
None.
miGetEmbeddedEventId
BYTE miGetEmbeddedEventId (void);
Description
Returns the latest embedded event ID.
Return Value
The latest embedded event ID – one of:
- MI_EMBEDDED_EVENT_NONE
- MI_EMBEDDED_EVENT_STARTUP
- MI_EMBEDDED_EVENT_TIMER
- MI_EMBEDDED_EVENT_GPIO
- MI_EMBEDDED_EVENT_SERIAL_IO
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:
- MI_EMBEDDED_EVENT_NONE – none (0x00)
- MI_EMBEDDED_EVENT_STARTUP – one of:
- MI_EMBEDDED_EVENT_TIMER – the timer ID.
- MI_EMBEDDED_EVENT_GPIO – the GPIO port number.
- MI_EMBEDDED_EVENT_SERIAL_IO – the serial IO port number.
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
- eventId: the ID of the embedded event – one of:
- eventInfo: the information associated with the embedded event. This depends upon the event ID as follows:
- MI_EMBEDDED_EVENT_TIMER – the timer ID.
- MI_EMBEDDED_EVENT_GPIO – the GPIO port.
- MI_EMBEDDED_EVENT_SERIAL_IO – the serial IO port number (bits 0-1) and the number of bytes (bits 2-7).
- MI_EMBEDDED_EVENT_I2C_SLAVE – The I2C event does not have any event info associated with it.
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
- behaviour: the required contactless behaviour:
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
- behaviour: the required behaviour:
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
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.
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.
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.
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:
- MI_ABEND_REASON_NO_ABEND
- MI_ABEND_REASON_FIREWALL_VIOLATION
- MI_ABEND_REASON_INVALID_PARAMETER
- MI_ABEND_REASON_INVALID_OPTION
- MI_ABEND_REASON_RESTRICTIONS_NOT_MET
- MI_ABEND_REASON_PRECONDITIONS_NOT_MET
- MI_ABEND_REASON_CRYPTO_ERROR
- MI_ABEND_REASON_SYSTEM_ERROR
- MI_ABEND_REASON_NOT_ENOUGH_RAM
- MI_ABEND_REASON_NOT_ENOUGH_NVM
- MI_ABEND_REASON_UNKNOWN_INSTRUCTION
- MI_ABEND_REASON_UNKNOWN_PRIMITIVE
- MI_ABEND_REASON_UNKNOWN_CODELET
- MI_ABEND_REASON_INVALID_CODELET_RET
- MI_ABEND_REASON_GP_PIN_ALREADY_INIT
- MI_ABEND_REASON_GP_PIN_NOT_INIT
- MI_ABEND_REASON_GP_PTC_PTL
- MI_ABEND_REASON_GP_NO_PERMISSION
- MI_ABEND_REASON_CRYPTO_NOT_PERMITTED
- MI_ABEND_REASON_MEL_PRIM_CALL_DEPTH
- MI_ABEND_REASON_PERIPHERAL_NO_PERMISSION
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
The high level event of a GPIO pin.
A high to low transition event on a GPIO pin.
The low level event of a GPIO pin.
A low to high transition event on a GPIO pin.
The output state of a GPIO pin when driven to Vcc_GPIO.
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
- num: the startup pin number (0 or 1)
- pin: the GPIO pin to allocate.
- state: the required startup state – one of:
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
- pin: the GPIO pin to monitor.
- event: the GPIO event:
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
- pin: the GPIO pin to set.
- state: one of:
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
- num: the startup pin number (0 or 1)
- state: the required state – one of:
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
- config: segment address of MI_I2C_SLAVE_CONFIG data structure.
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
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.
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:
- MI_SERIAL_IO_RECEIVE_BUFFER_EMPTY
- MI_SERIAL_IO_RECEIVE_BUFFER_NON_EMPTY
- MI_SERIAL_IO_RECEIVE_BUFFER_FULL
- MI_SERIAL_IO_RECEIVE_BUFFER_OVERFLOWED
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
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
Timer units of hours.
MI_TIMER_TIME_UNIT_MILLISECONDS
Timer units of milliseconds.
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
- time: the required time. If zero then a count-up timer is allocated, otherwise a count-down timer is allocated.
- units: the timer units, one of:
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.
