@CHIP-RTOS - IP Security Application Programmer's Interface

IP Security

These interfaces allow control over the IP Security operation.   This set of API is available only in the SC1x3/SC2x products.

IP Security Overview
IP Security Data Structures
IP Security Known Problems

IP Security Interrupt 0xAC Services

IP Security Initialization

IKE Transforms

Preshared Keys

This function is used to add IP security policies.

Parameters

AX

0xCF00 (= IPSEC_ADD_POLICY)

DS:BX

Pointer to an array of CX tIPSEC_POLICY_PAIR structures.

ES:DI

Pointer to an array of tIPSEC_POLICY_SELECTOR structures.

DX:SI

Pointer to an array of tIPSEC_POLICY_CONTENT structures.

CX

Number of data structures in array at DS:BX.

Return Value

DX = 0, AX = 0 success
DX != 0 AX: contains error code

Comments

The IP security must be enabled prior to using this API.

The tIPSEC_POLICY_PAIR structures at DS:BX are used to connect the members of the other two structure arrays, mapping policy selectors to policy content.   Care must be taken to assure that these indexes map to existing structures within these two arrays.


Refer to the C-Library function IPsec_Add_Policy() for more information about this API.

Beck C-Library Usage

IPsec_Add_Policy() - Set policy

Related Topics

Clear Policy IPSEC_CLEAR_POLICY

Restore Policy IPSEC_RESTORE_POLICY from file

Set IKE transform IPSEC_IKE_PHASE1_SET

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This function deletes the IP security policies.

Parameters

AX

0xCF01 (= IPSEC_CLEAR_POLICY)

Return Value

DX = 0, AX = 0 success
DX != 0 AX: contains error code

Comments

The IP security must be enabled prior to using this API.

A default policy of BYPASS for all IP addresses will be used following this action.

Beck C-Library Usage

IPsec_Clear_Policy() - Clear policy

Related Topics

Set Policy IPSEC_ADD_POLICY

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This add preshared key for use with Internet Key Exchange (IKE) protoocol with the specified remote IP address.

Parameters

AX

0xCF02 (= IPSEC_ADD_PRESHARED_KEY)

ES:BX

Pointer to a zero terminated ASCII string specifying the remote IP address.

DX:SI

Pointer to zero terminated ASCII string containing the preshared key.

Return Value

DX = 0, AX = 0 success
DX != 0 AX: contains error code

Comments

The IP security must be enabled prior to using this API.

The remote IP address may be either IPv4 of IPv6.   Domain names must be resolved first by the caller and are not supported by this API.

Beck C-Library Usage

IPsec_Add_Preshared_Key()

Related Topics

IPSEC_REMOVE_PRESHARED_KEY

IPSEC_CLEAR_PRESHARED_KEYS

CHIP.INI PRESHARED_KEY

getHostByName() API

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This function removes a preshared key from the database for the specified remote IP address.

Parameters

AX

0xCF03 (= IPSEC_REMOVE_PRESHARED_KEY)

ES:BX

Pointer to a zero terminated ASCII string specifying the remote IP address.

Return Value

DX = 0, AX = 0 success
DX != 0 AX: contains error code

Comments

The IP security must be enabled prior to using this API.

The remote IP address may be either IPv4 of IPv6.   Domain names must be resolved first by the caller and are not supported by this API.

Beck C-Library Usage

IPsec_Remove_Preshared_Key()

Related Topics

IPSEC_ADD_PRESHARED_KEY

IPSEC_CLEAR_PRESHARED_KEYS

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This function clears all preshared keys from the database used by the Internet Key Exchange (IKE) protoocol.

Parameters

AX

0xCF04 (= IPSEC_CLEAR_PRESHARED_KEYS)

-- none --

Return Value

DX = 0, AX = 0

Beck C-Library Usage

IPsec_Clear_Preshared_Keys()

Related Topics

IPSEC_ADD_PRESHARED_KEY

IPSEC_REMOVE_PRESHARED_KEY

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

This function activates the IP Security functionality in the TCP/IP stack.

Parameters

AX

0xCF05 (= IPSEC_START)

-- none --

Return Value

DX = 0, AX = 0 on success
else on failure AX viewed as a signed value:

AX less than 5000:   look here for error code description.   A error code of 235, "Operation would block", is returned if IP security initialization is pending on DHCP IP address configuration.

5000 <= AX < 6000:   The POLICY_FILE restore operation has failed.   Subtract 5100 from this value and check here for resulting error value.

6000 <= AX < 7000:   The PRESHARED_KEY loading failed.   Subtract 6100 from this error code and look here for a description of the resulting error code.

Comments

Alternatively, the IP Security can be started by setting the IPSEC ENABLE value in the CHIP.INI.   If the function has not already been activated, then this API will respond to the POLICY_FILE and PRESHARED_KEY entries in the CHIP.INI file.

Beck C-Library Usage

IPsec_Start()

Related Topics

IKE command

IPSEC_ADD_POLICY

IPSEC_RESTORE_POLICY

IPSEC_ADD_PRESHARED_KEY

IPSEC_STATUS

Set IKE transform IPSEC_IKE_PHASE1_SET

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

Read out the status of the IP Security function.

Parameters

AX

0xCF06 (= IPSEC_STATUS)

-- none --

Return Value

DX = 0, AX = enumerator as follow:

IPSEC_OFF (0) - Not started yet.
IPSEC_FAILED (1) - Startup failed, perhaps insufficient memory.
IPSEC_AWAITING_DHCP (2) - Awaiting Ethernet IP address for IKE.
IPSEC_READY (3) - Ready for operation.

BX is the error code which is non-zero if state is IPSEC_FAILED.
CX is the latest IKE error status.

Beck C-Library Usage

IPsec_Status()

Related Topics

IPSEC_START

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.15	V1.00

Set IP security and IKE options.

Parameters

AX

0xCF07 (= IPSEC_SET_OPTIONS)

BX

Option selector

CX

Option value

Return Value

DX = 0, AX = 0:   Success
DX = -1, AX = -1:   Failure, invalid option or value

Comments

This function allows the IP Security and Internet Key Exchange (IKE) protocol options to be adjusted at run-time.   The IP Security function must have been started either from the CHIP.INI or IPsec_Start() API before using this API.

A specification of the available options and their values is provided with the IPsec_Set_Option() C-library function description.

Beck C-Library Usage

IPsec_Set_Option()

Related Topics

IKE_PH1_AGGRESSIVE definition in CHIP.INI file

IKE_PH2_PFS definition in CHIP.INI file

IPSEC_START

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

Specify a transform for IKE's phase 1 proposal.

Parameters

AX

0xCF08 (= IPSEC_IKE_PHASE1_SET)

ES:BX

Pointer to a tIPSEC_TKE_PHASE1 data structure used to specify the transform's parameters.   This data is not altered by this API.   A copy of this data is made, so the caller's image need not persist beyond the return from this function.

CX

Index 0 or 1 selects which of the two phase 1 IKE transforms is to be set.

Return Value

DX = 0, AX = error code,

Comments

This function adds a user specified phase 1 transform to IKE’s phase 1 proposal.   The user is able to configure up to two such transforms.   The most preferred has index 0, the less preferred has index 1.   If the user configures either of these, the default transform will not be used.

When neither of these optional phase1 proposals is set, the default transform will be used in the phase 1 proposal.   This default transform has the following settings:

Encryption Algorithm:   3DES CBC
Hash Algorithm:         SHA1
Diffie-Hellman Group:   2
SA Lifetime seconds:   86400 seconds (=1 day)
SA Lifetime kBytes:   0x10000 kByte (=64 MByte)

The default authentication method is preshared key unless a local certificate has been specified in the CHIP.INI file.

If this API is used to set both of the phase 1 transforms available for user control, then the authentication method specified in these two transforms must be set the same.   Otherwise unpredictable operation may result.

Beck C-Library Usage

IPsec_IKE_Phase1_Set()

Related Topics

IPSEC_IKE_PHASE1_DELETE

IKE_PH1_AGGRESSIVE definition in CHIP.INI file

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

Remove one of the two optional user phase 1 IKE transforms.

Parameters

AX

0xCF09 (= IPSEC_IKE_PHASE1_DELETE)

CX

Index 0 or 1 selects which of two phase 1 IKE transforms is to be deleted.

Return Value

DX = 0, AX = error code.

Comments

The specified phase 1 transform is removed.   If both user settable phase 1 transforms are not present, then the default transform will be used.

Beck C-Library Usage

IPsec_IKE_Phase1_Delete()

Related Topics

IPSEC_IKE_PHASE1_SET

IKE_PH1_AGGRESSIVE definition in CHIP.INI file

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00

Restore policy and/or preshared keys from file.

Parameters

AX

0xCF0A (= IPSEC_RESTORE_POLICY)

ES:BX

Pointer to path of binary file containing the IP security policies and any desired preshared keys.

Return Value

DX = 0, AX = 0 on success
On failure AX indicates error:

-3 :    Policy file exceeded 64 Kbyte size limit
-4 :    Work buffer memory allocation failed
-5 :    Invalid policy file contents
202 :   Policy file open failed

Between 1000 and 1999 :

Policy add operation failed.   Subtract 1000 from this error code and look here for resulting error code description.

Between 2000 and 2999:

Preshared key add operation failed.   Subtract 2000 from this error code and look here for resulting error code description.

Comments

This API allows IP security policy and/or preshared keys to be set based on the contents of a binary policy file in same manner as done with the POLICY_FILE CHIP.INI file entry.

Beck C-Library Usage

IPsec_Restore_Policy()

Related Topics

IPSEC_ADD_POLICY

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.07	V1.00