IPC@CHIP® RTOS-PPC – API Documentation

Header image

Main page


CHIP.INI [IPSEC]


[IPSEC]
ENABLE=0/1

Disable/Enable IP security. Note that the IP Security may also be started at run time with the IPsec_Start() API.
Default:
By default IP security is disabled.
Example:
 [IPSEC]
 ENABLE=1
Since:
SC2x3 V1.00
SC2x3 V1.00


[IPSEC]
IKE_BUF_SIZE=Receiver buffer size

This entry specifies the size of the receiver buffer used by the Internet Key Exchange (IKE).

The default IKE receiver buffer size may be too small for cases where a significant chain of certificates is to be received from the IKE peer. The sum of the certificate file sizes in the anticipated CA chain can be used to judge the size of the required receiver buffer. Padding this sum by an additional 300 bytes should provide sufficient buffer space.

This entry will be limited internally to the range from 1024 bytes minimum up to 10000 bytes maximum.

Note that the IKE console command lists the peak IKE message size that has been received from the IKE peers. Appearance of the IKE error 100 indicates that you need to select a larger receiver buffer size with this INI file entry.
Default:
The default IKE receiver buffer size is 2048 bytes.
Example:
 [IPSEC]
 IKE_BUF_SIZE=4000
Since:
SC2x3 V1.00


[IPSEC]
IKE_CACERTx=CA certificate file name

File name(s) for IKE CA certificates. IKE_CACERT0 must be the name of the IKE's root CA certificate. Up to four further CA certifications can be listed with tags IKE_CACERT1 up to IKE_CACERT4 to indicate a certification chain. Possible file formats are *.PEM and *.DER.

The system scans for these entries in CHIP.INI starting at IKE_CACERT0 and terminates the scan at the first non-existant entry in the sequence.

Key lengths longer than 2048 bits are not supported.
Default:
No default.
Example:
 [IPSEC]
 IKE_CACERT0=ROOTCERT.DER
Since:
SC2x3 V1.00


[IPSEC]
IKE_CLICACERTx=File name of IKE peer's CA certificate

Up to five CA certificates for IKE peers may be specified with the 'x' in the above tag replaced with numbers '0' through '4'. The system scans for these entries in CHIP.INI starting at '0' and terminates the scan at the first non-existant entry.

Key lengths longer than 2048 bits are not supported.
Default:
No default.
Example:
 [IPSEC]
 IKE_CLICACERT0=CACERT.DER
Since:
SC2x3 V1.00


[IPSEC]
IKE_FQDN=Fully Qualified Domain Name

This entry specifies the Fully Qualified Domain Name to be used in the IKE identification payloads. A check for this entry is made just before the IKE task is started.
Default:
No default. (No FQDN is output in IKE ID payloads unless this entry is present.)
Example:
 [IPSEC]
 IKE_FQDN=myDomainName
Comments
IKE outputs an identification payload both for phase 1 (Main Mode) and phase 2 (Quick Mode). For phase 1, this FQDN ID will only be used when preshared key form of identification is used. When certificates are used, the ID sent for phase 1 will always be the ID_DER_ASN1_DN (9) type with the payload containing the ID information extracted from the certificate.

Explicit control over whether the FQDN form of ID is used in either IKE phase 1 or phase 2 can be specified by prefixing the domain name with either "PH1," or "PH2," as in the following example which calls for FQDN ID use in phase 1, but not for phase 2.
Example with an IKE phase specifier prefix:
 [IPSEC]
 IKE_FQDN=PH1,myDomainName
More Notes
The "PH1," or "PH2," prefixes must be in upper case as shown, with no space characters before the domain name. No FQDN ID will be used for the above example when certificates are used for identification, as was noted above. This example would apply only when a preshared key is used.

If an '@' character appears in the FQDN string then the ID_USER_FQDN (3) type ID payload is sent instead of the ID_FQDN (2) type.

The configuration resulting from this CHIP.INI entry is visible at the IKE shell command.
Since:
SC2x3 V1.07


[IPSEC]
IKE_KEYFILE=File name of the IKE key file

Specifies the name of private and public key file used for IKE. Possible file formats are *.PEM and *.DER.

Key lengths longer than 2048 bits are not supported.
Default:
No default.
Example:
 [IPSEC]
 IKE_KEYFILE=PRIVKEY.DER
Since:
SC2x3 V1.00


[IPSEC]
IKE_LOCALCERT=File name of our certificate

Defines the name of this system's local certificate. Possible file formats are *.PEM and *.DER.

If this INI file entry is present and the certificate is successfully loaded, then the IKE will use Public Key Infrastructure (PKI) authentication method in phase 1 of the key negotiation process unless:
  • 1. The peer has initiated the IKE negotiation and has requested the use of preshared key for authentication.
  • 2. The user has specified preshared key authorization method in the optional transform(s) set with the IPsec_IKE_Phase1_Set() API.
The IKE_KEYFILE and IKE_CACERT0 files must also be specified for PKI operation.
Default:
No default.
Example:
 [IPSEC]
 IKE_LOCALCERT=OURCERT.DER
Since:
SC2x3 V1.00


[IPSEC]
IKE_PH1_AGGRESSIVE=IKE Phase 1 Aggressive mode

This entry specifies the Internet Key Exchange (IKE) should use aggressive mode for phase 1 SA negotiation.

If this option is deselected (value 0), then it causes the phase 1 IKE negotiation to operate in the "main mode", also referred to as Identify Protection Exchange. (See RFC 2408 section 4.5.)

When this switch is set to 1 as shown in the example, then the phase 1 IKE will use the Aggressive Exchange which does not hide identifies. A few less messages must travel between computers in this case. (See RFC 2408 section 4.7.)

Note: Microsoft operating systems have not supported this mode. You will likely get an IKE error code 7, "Invalid exchange type", when Aggressive mode is used with a Microsoft peer system.
Default:
By default this option is deselected (value 0).
Example:
 [IPSEC]
 IKE_PH1_AGGRESSIVE=1
Since:
SC2x3 V1.00


[IPSEC]
IKE_PH2_PFS=PFS mode for IKE phase 2

This entry specifies the PFS mode to be used by Internet Key Exchange (IKE) Quick Mode.

Perfect Forward Secrecy (PFS) mode will be used during Quick Mode SA key negotiation when this switch is set to '1'.

PFS mode can be disabled by setting this switch value to zero.

Refer to RFC 2409 section 3.3 for a precise definition of PFS.
Default:
Perfect Forward Secrecy (PFS) mode will be used.
Example:
 [IPSEC]
 IKE_PH2_PFS=0
Since:
SC2x3 V1.00


[IPSEC]
IKE_PRIORITY=priority

This entry specifies the priority at which the Internet Key Exchange task, "_IKE", executes.

This task can occupy 100% of the CPU for an expended period of time (seconds) during the key exchange processing. Consequently, this low default task priority is assigned to it.
Default:
Default priority is 100.
Example:
 [IPSEC]
 IKE_PRIORITY=35


[IPSEC]
NAT=0/1

Disable/Enable IP Security transversal of NAT devices (Network Address Translator).

When this mode is enabled, the IKE will perform NAT detection and negotiate NAT-transversal mode with a peer as specified in RFC-3947 and use, when necessary, the UDP encapsulated ESP per RFC-3948 in order to provide IP security across the NAT. The UDP port 4500 is used for this purpose.

Normally it does no harm to leave this switch in its default enabled state. However there may be cases with some routers that interfere with the IKE operation as they try to "help" due to being IP Security aware, where it becomes necessary to disable the NAT-Transversal functionality in the IPC@CHIP® in order to get the IP Security to operate across a NAT.

Note that AH protocol (Authentication Header) is not supported when a NAT is present on the path between IPsec peers. The security policy must be set accordingly (ESP only!).

Note that the top level ENABLE switch must be enabled for this switch to have affect.
Default:
By default IP Security NAT-Transveral mode is enabled.
Example:
 [IPSEC]
 NAT=0
Since:
SC2x3 V1.00


[IPSEC]
NAT_LINGER=NAT Keep-Alive Linger Time

This entry specifies the number of minutes that the NAT keep-alive UDP packets will continue to be sent out after the related SA (Security Association) have been deleted. (Ref: RFC 3948 section 4.)

The range of legal entry values is from 1 to 720 minutes. Values outside this range will be changed to the nearest in range value.

The purpose of the NAT keep-alive UDP packets is to maintain the NAT address/port mappings. The linger time allows these mappings to be preserved as SA (Security Association) are re-negotiated after SA timeouts have occurred.
Default:
Default NAT keep alive linger time is 5 minutes.
Example:
 [IPSEC]
 NAT_LINGER=6
Since:
SC2x3 V1.00


[IPSEC]
NAT_TIMEOUT=NAT Keep-Alive Packet Interval

Specify the interval in seconds at which NAT keep-alive UDP packets will be output when IP Security SA (Security Association) are established with the IPC@CHIP® lying behind a NAT device. (Ref: RFC 3948 section 4.)

The range of legal entry values here is from 1 to 3600 seconds. Values outside this range will be changed to the nearest in range value.
Default:
Default interval is 20 seconds.
Example:
 [IPSEC]
 NAT_TIMEOUT=30
Since:
SC2x3 V1.00


[IPSEC]
POLICY_FILE=filename

Restore IP Security Policies from file. This entry specifies a binary file that contains the IP Security policies and/or preshared keys to be installed either at startup (assuming IPSEC ENABLE set to 1) or at run time when IPsec_Start() API is called.

The file can be constructed with the IPsec_Store_Policy() C-library function or with Beck's IP Security Policy Editor tool, BeckIPSec, available for use with a Windows PC. The file extension on this policy data file can be anything. The IPS extension is the convention used by the BeckIPSec tool.
Default:
No default.
Example:
 [IPSEC]
 POLICY_FILE=ipsec.ips
Since:
SC2x3 V1.00


[IPSEC]
PRESHARED_KEY=IKE Peer ID ; Key String

This entry specifies both the identity of an IKE (Internet Key Exchange) peer and an ASCII string to be installed for a preshared key used with that peer. A semicolon is used to delimit the two fields of this entry.

Only one preshared key may be specified in this INI file. Additional keys may be added at runtime using the IPsec_Add_Preshared_Key() API or from a policy file().

The peer identity can be a string specifying an IPv4 address, an IPv6 address, a fully qualified domain name or a user name. This string must match the manner that the peer uses to identify itself within the IKE protocol.

White space should be avoided immediately after the semicolon, otherwise this white space will be included as the first part of your key.

The total string entered after the "PRESHARED_KEY=" is limited to 260 characters. The string pair is truncated after 260 characters total.
Default:
No default.
Example:
 [IPSEC]
 PRESHARED_KEY=192.168.30.145;MyPresharedKey#1
Since:
SC2x3 V1.00





Top of page | Main page

Copyright © 2017 Beck IPC GmbH
Generated on Thu Jan 26 16:21:35 2017 by Doxygen 1.6.1