www.beck-ipc.com

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


    IPC@CHIP® Documentation Index

IP Security

IP Security API

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

Service is selected by index in AX register, where AH part is 0xCF in each case.

IP Security Initialization

  • 0xCF00:_IPSEC_ADD_POLICY
  • 0xCF01:_IPSEC_CLEAR_POLICY
  • 0xCF05:_IPSEC_START
  • 0xCF06:_IPSEC_STATUS
  • 0xCF07:_IPSEC_SET_OPTIONS
  • 0xCF0A:_IPSEC_RESTORE_POLICY

  • IKE Transforms

  • 0xCF08:_IPSEC_IKE_PHASE1_SET
  • 0xCF09:_IPSEC_IKE_PHASE1_DELETE

  • Preshared Keys

  • 0xCF02:_IPSEC_ADD_PRESHARED_KEY
  • 0xCF03:_IPSEC_REMOVE_PRESHARED_KEY
  • 0xCF04:_IPSEC_CLEAR_PRESHARED_KEYS


  • Interrupt 0xAC service 0xCF00:     IPSEC_ADD_POLICY

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF01:     IPSEC_CLEAR_POLICY

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF02:     IPSEC_ADD_PRESHARED_KEY

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF03:     IPSEC_REMOVE_PRESHARED_KEY

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF04:     IPSEC_CLEAR_PRESHARED_KEYS

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF05:     IPSEC_START

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF06:     IPSEC_STATUS

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.15V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF07:     IPSEC_SET_OPTIONS

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF08:     IPSEC_IKE_PHASE1_SET

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF09:     IPSEC_IKE_PHASE1_DELETE

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page
    Interrupt 0xAC service 0xCF0A:     IPSEC_RESTORE_POLICY

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.07V1.00

    Top of list
    Index page


    End of document