Ipsec-Ikev2 Technical Reference
Total Page:16
File Type:pdf, Size:1020Kb
IPSec-IKEv2 Technical Reference IPSec-IKEv2 Technical Reference Interniche Legacy Document Version 1.00 Date: 17-May-2017 17:22 All rights reserved. This document and the associated software are the sole property of HCC Embedded. Reproduction or duplication by any means of any portion of this document without the prior written consent of HCC Embedded is expressly forbidden. HCC Embedded reserves the right to make changes to this document and to the related software at any time and without notice. The information in this document has been carefully checked for its accuracy; however, HCC Embedded makes no warranty relating to the correctness of this document. Copyright HCC Embedded 2017 1 www.hcc-embedded.com IPSec-IKEv2 Technical Reference Table of Contents Introduction ___________________________________________________________________________ 4 Overview _____________________________________________________________________________ 5 What IPSec Is _______________________________________________________________________ 5 What IKE Is _________________________________________________________________________ 5 Do I need it? _____________________________________________________________________ 5 IKEv1 vs IKEv2 ___________________________________________________________________ 5 IPSec _______________________________________________________________________________ 6 Product Architecture, Packet Flow _______________________________________________________ 6 Packet Interface ______________________________________________________________________ 8 Packet Classification __________________________________________________________________ 9 Encapsulation - De-encapsulation Engine _________________________________________________ 9 Management Interface _________________________________________________________________ 9 Security Policy Database ______________________________________________________________ 10 Security Association Database - SAD ____________________________________________________ 11 Security Policy Options _______________________________________________________________ 11 Dummy Packets ____________________________________________________________________ 12 TFC Padding _______________________________________________________________________ 13 X.509 _____________________________________________________________________________ 13 IPSec API _________________________________________________________________________ 14 IPSec Packet APIs _______________________________________________________________ 14 PacketDecapsulateSync ______________________________________________________ 15 PacketEncapsulateSync ______________________________________________________ 16 PacketGetPolicy _____________________________________________________________ 17 Packet API ______________________________________________________________________ 18 Management API ____________________________________________________________ 18 IPSecAdminAddBypassPolicy __________________________________________________ 19 IPSecAdminAddDropPolicy ____________________________________________________ 20 IPSecAdminAddPolicy ________________________________________________________ 21 IPSecMgmtAddPolicy _________________________________________________________ 23 IPSecMgmtAddSA ___________________________________________________________ 24 IPSec CLI _________________________________________________________________________ 25 ipsec addsa _____________________________________________________________________ 26 ipsec delsa _____________________________________________________________________ 32 ipsec flush ______________________________________________________________________ 33 ipsec netstat ____________________________________________________________________ 34 IPSec Messaging Interface ____________________________________________________________ 35 Messages Overview ______________________________________________________________ 35 Message Header _________________________________________________________________ 36 Message Types __________________________________________________________________ 37 Message Description ______________________________________________________________ 38 MGMT_TYPE_APP_REGISTER ________________________________________________ 38 MGMT_TYPE_CLONE_POLICY ________________________________________________ 38 Copyright HCC Embedded 2017 2 www.hcc-embedded.com IPSec-IKEv2 Technical Reference MGMT_TYPE_INITIAL_CONTACT ______________________________________________ 38 MGMT_TYPE_DELETE_SPIs __________________________________________________ 38 MGMT_TYPE_ACQUIRE_FAIL _________________________________________________ 39 MGMT_TYPE_GET_SPI ______________________________________________________ 39 IPSec Error Codes ___________________________________________________________________ 40 IKE ________________________________________________________________________________ 42 IKE Quick Start _____________________________________________________________________ 42 IKE Architecture _____________________________________________________________________ 44 IKE Cryptographic Library _____________________________________________________________ 44 IKE Startup ________________________________________________________________________ 44 IKE Debugging and Packet Decoder _____________________________________________________ 46 Configuration _______________________________________________________________________ 47 IKE Administrative APIs _______________________________________________________________ 47 Policy __________________________________________________________________________ 47 Remote ________________________________________________________________________ 47 IKE CLI ___________________________________________________________________________ 48 ike netstat ______________________________________________________________________ 49 ike flush ________________________________________________________________________ 50 ipsec policy _____________________________________________________________________ 51 ike reload _______________________________________________________________________ 54 ike remote ______________________________________________________________________ 55 ike commands ___________________________________________________________________ 59 ike debug _______________________________________________________________________ 60 Compile-time considerations ___________________________________________________________ 61 Examples: Securing communications between two InterNiche-based systems ______________________ 62 Example 1: TCP connection in transport mode using a Pre-Shared Key with IPSec and IKEv2 _______ 63 Step 1: Configure hosts and verify pre-connection status __________________________________ 63 Step 2: Verify policy configuration ____________________________________________________ 63 Step 3: Establish a TCP connection and verify link status _________________________________ 64 Example 2: ICMP connection in tunnel mode using X.509 certificate-based authentication ___________ 65 Step 1: Configure hosts and verify the pre-connection status _______________________________ 65 Step 2: Verify the policy configuration _________________________________________________ 65 Step 3: Execute __________________________________________________________________ 65 Porting to non-InterNiche TCP/IP stacks ___________________________________________________ 66 IP Packet Flow ______________________________________________________________________ 67 Porting Overview ____________________________________________________________________ 68 System Dependencies ____________________________________________________________ 68 IPSec Configuration ______________________________________________________________ 68 Packet Buffers ___________________________________________________________________ 68 Initialization _____________________________________________________________________ 68 The Packet Interface ______________________________________________________________ 68 OS interaction ___________________________________________________________________ 69 TCP-IP _________________________________________________________________________ 69 Copyright HCC Embedded 2017 3 www.hcc-embedded.com IPSec-IKEv2 Technical Reference 1 Introduction This manual describes InterNiche's IPSec and IKE and is intended for both the developer who wants to understand its internal architecture and for the application developer desiring only to know how to build, configure and use it within an embedded device. InterNiche's IPSec, when used with Kerberos or Pre- Shared Keys does not require IKE. Additionally, if only one of IKEv1 or IKEv2 are required then the other can be removed at compile-time. Copyright HCC Embedded 2017 4 www.hcc-embedded.com IPSec-IKEv2 Technical Reference 2 Overview 2.1 What IPSec Is InterNiche's IPSec is a software module that provides bulk encryption and authentication between endpoints and gateways over IPv4 and IPv6. It implements the Authentication Header (AH) and Encapsulating Security Protocol (ESP) of the IETF's security framework. Confirguration information and keys are provided either manually (via CLI pr APIs) or through IKE. 2.2 What IKE Is The Internet Key Exchange (IKE) protocol is used for key agreement and key management within IPSec. It provides a scalable method of generating security associations for IPSec protocols. The protocol includes system authentication, key agreement and security association generation. This protocol is specified by the IETF standard RFC 2409 and RFC 4306