From 58d26e02cd8686e177eebb9fb81e6b17798bbb30 Mon Sep 17 00:00:00 2001 From: Rene Mayrhofer Date: Mon, 6 Nov 2006 19:00:10 +0000 Subject: Load /tmp/tmp.IBEBMao893/strongswan-2.8.0+dfsg into branches/source-dist/debian/strongswan. --- doc/draft-richardson-ipsec-opportunistic.txt | 2688 --------------------- doc/draft-richardson-ipsec-rr.txt | 840 ------- doc/draft-spencer-ipsec-ike-implementation.nr | 1203 --------- doc/draft-spencer-ipsec-ike-implementation.txt | 1232 ---------- doc/manpage.d/ipsec.8.html | 215 -- doc/manpage.d/ipsec.conf.5.html | 1830 -------------- doc/manpage.d/ipsec.secrets.5.html | 227 -- doc/manpage.d/ipsec__confread.8.html | 58 - doc/manpage.d/ipsec__copyright.8.html | 62 - doc/manpage.d/ipsec__include.8.html | 67 - doc/manpage.d/ipsec__keycensor.8.html | 64 - doc/manpage.d/ipsec__plutoload.8.html | 64 - doc/manpage.d/ipsec__plutorun.8.html | 70 - doc/manpage.d/ipsec__realsetup.8.html | 68 - doc/manpage.d/ipsec__secretcensor.8.html | 65 - doc/manpage.d/ipsec__startklips.8.html | 63 - doc/manpage.d/ipsec__updown.8.html | 63 - doc/manpage.d/ipsec_addrbytesof.3.html | 232 -- doc/manpage.d/ipsec_addrbytesptr.3.html | 232 -- doc/manpage.d/ipsec_addrcmp.3.html | 274 --- doc/manpage.d/ipsec_addrinsubnet.3.html | 274 --- doc/manpage.d/ipsec_addrlenof.3.html | 232 -- doc/manpage.d/ipsec_addrtoa.3.html | 448 ---- doc/manpage.d/ipsec_addrtosubnet.3.html | 238 -- doc/manpage.d/ipsec_addrtot.3.html | 569 ----- doc/manpage.d/ipsec_addrtypeof.3.html | 232 -- doc/manpage.d/ipsec_anyaddr.3.html | 166 -- doc/manpage.d/ipsec_atoaddr.3.html | 448 ---- doc/manpage.d/ipsec_atoasr.3.html | 294 --- doc/manpage.d/ipsec_atosa.3.html | 347 --- doc/manpage.d/ipsec_atosubnet.3.html | 448 ---- doc/manpage.d/ipsec_atoul.3.html | 266 -- doc/manpage.d/ipsec_auto.8.html | 416 ---- doc/manpage.d/ipsec_barf.8.html | 150 -- doc/manpage.d/ipsec_bitstomask.3.html | 122 - doc/manpage.d/ipsec_broadcastof.3.html | 107 - doc/manpage.d/ipsec_calcgoo.8.html | 78 - doc/manpage.d/ipsec_copyright_notice.3.html | 94 - doc/manpage.d/ipsec_datatot.3.html | 439 ---- doc/manpage.d/ipsec_eroute.5.html | 370 --- doc/manpage.d/ipsec_eroute.8.html | 421 ---- doc/manpage.d/ipsec_goodmask.3.html | 122 - doc/manpage.d/ipsec_hostof.3.html | 107 - doc/manpage.d/ipsec_ikeping.8.html | 137 -- doc/manpage.d/ipsec_initaddr.3.html | 232 -- doc/manpage.d/ipsec_initsaid.3.html | 453 ---- doc/manpage.d/ipsec_initsubnet.3.html | 238 -- doc/manpage.d/ipsec_isanyaddr.3.html | 166 -- doc/manpage.d/ipsec_isloopbackaddr.3.html | 166 -- doc/manpage.d/ipsec_isunspecaddr.3.html | 166 -- doc/manpage.d/ipsec_keyblobtoid.3.html | 174 -- doc/manpage.d/ipsec_klipsdebug.5.html | 229 -- doc/manpage.d/ipsec_klipsdebug.8.html | 264 -- doc/manpage.d/ipsec_look.8.html | 76 - doc/manpage.d/ipsec_loopbackaddr.3.html | 166 -- doc/manpage.d/ipsec_lwdnsq.8.html | 400 --- doc/manpage.d/ipsec_mailkey.8.html | 97 - doc/manpage.d/ipsec_manual.8.html | 414 ---- doc/manpage.d/ipsec_maskof.3.html | 238 -- doc/manpage.d/ipsec_masktobits.3.html | 122 - doc/manpage.d/ipsec_masktocount.3.html | 238 -- doc/manpage.d/ipsec_networkof.3.html | 238 -- doc/manpage.d/ipsec_newhostkey.8.html | 196 -- doc/manpage.d/ipsec_optionsfrom.3.html | 275 --- doc/manpage.d/ipsec_pf_key.5.html | 176 -- doc/manpage.d/ipsec_pf_key.8.html | 122 - doc/manpage.d/ipsec_pluto.8.html | 1824 -------------- doc/manpage.d/ipsec_portof.3.html | 143 -- doc/manpage.d/ipsec_prng.3.html | 204 -- doc/manpage.d/ipsec_prng_bytes.3.html | 204 -- doc/manpage.d/ipsec_prng_final.3.html | 204 -- doc/manpage.d/ipsec_prng_init.3.html | 204 -- doc/manpage.d/ipsec_ranbits.8.html | 147 -- doc/manpage.d/ipsec_rangetoa.3.html | 294 --- doc/manpage.d/ipsec_rangetosubnet.3.html | 116 - doc/manpage.d/ipsec_rsasigkey.8.html | 401 --- doc/manpage.d/ipsec_sameaddr.3.html | 274 --- doc/manpage.d/ipsec_sameaddrtype.3.html | 274 --- doc/manpage.d/ipsec_samesaid.3.html | 274 --- doc/manpage.d/ipsec_samesubnet.3.html | 274 --- doc/manpage.d/ipsec_samesubnettype.3.html | 274 --- doc/manpage.d/ipsec_satoa.3.html | 347 --- doc/manpage.d/ipsec_satot.3.html | 453 ---- doc/manpage.d/ipsec_send-pr.8.html | 427 ---- doc/manpage.d/ipsec_setportof.3.html | 143 -- doc/manpage.d/ipsec_setup.8.html | 237 -- doc/manpage.d/ipsec_showdefaults.8.html | 82 - doc/manpage.d/ipsec_showhostkey.8.html | 269 --- doc/manpage.d/ipsec_showpolicy.8.html | 88 - doc/manpage.d/ipsec_sockaddrlenof.3.html | 143 -- doc/manpage.d/ipsec_sockaddrof.3.html | 143 -- doc/manpage.d/ipsec_spi.5.html | 305 --- doc/manpage.d/ipsec_spi.8.html | 790 ------ doc/manpage.d/ipsec_spigrp.5.html | 193 -- doc/manpage.d/ipsec_spigrp.8.html | 280 --- doc/manpage.d/ipsec_splitkeytoid.3.html | 174 -- doc/manpage.d/ipsec_subnetinsubnet.3.html | 274 --- doc/manpage.d/ipsec_subnetishost.3.html | 274 --- doc/manpage.d/ipsec_subnetof.3.html | 107 - doc/manpage.d/ipsec_subnettoa.3.html | 448 ---- doc/manpage.d/ipsec_subnettot.3.html | 569 ----- doc/manpage.d/ipsec_subnettypeof.3.html | 238 -- doc/manpage.d/ipsec_tnatoaddr.3.html | 569 ----- doc/manpage.d/ipsec_tncfg.5.html | 175 -- doc/manpage.d/ipsec_tncfg.8.html | 195 -- doc/manpage.d/ipsec_trap_count.5.html | 74 - doc/manpage.d/ipsec_trap_sendcount.5.html | 72 - doc/manpage.d/ipsec_ttoaddr.3.html | 569 ----- doc/manpage.d/ipsec_ttodata.3.html | 439 ---- doc/manpage.d/ipsec_ttosa.3.html | 453 ---- doc/manpage.d/ipsec_ttosubnet.3.html | 569 ----- doc/manpage.d/ipsec_ttoul.3.html | 310 --- doc/manpage.d/ipsec_ultoa.3.html | 266 -- doc/manpage.d/ipsec_ultot.3.html | 310 --- doc/manpage.d/ipsec_unspecaddr.3.html | 166 -- doc/manpage.d/ipsec_verify.8.html | 107 - doc/manpage.d/ipsec_version.3.html | 94 - doc/manpage.d/ipsec_version.5.html | 103 - doc/manpage.d/ipsec_version_code.3.html | 94 - doc/manpage.d/ipsec_version_string.3.html | 94 - doc/manpage.d/ipsec_whack.8.html | 1824 -------------- doc/src/draft-richardson-ipsec-opportunistic.html | 2456 ------------------- doc/src/draft-richardson-ipsec-opportunistic.xml | 2519 ------------------- doc/src/draft-richardson-ipsec-rr.html | 659 ----- doc/src/draft-richardson-ipsec-rr.xml | 560 ----- doc/utils/rfc_pg.c | 2 +- 126 files changed, 1 insertion(+), 44761 deletions(-) delete mode 100644 doc/draft-richardson-ipsec-opportunistic.txt delete mode 100644 doc/draft-richardson-ipsec-rr.txt delete mode 100644 doc/draft-spencer-ipsec-ike-implementation.nr delete mode 100644 doc/draft-spencer-ipsec-ike-implementation.txt delete mode 100644 doc/manpage.d/ipsec.8.html delete mode 100644 doc/manpage.d/ipsec.conf.5.html delete mode 100644 doc/manpage.d/ipsec.secrets.5.html delete mode 100644 doc/manpage.d/ipsec__confread.8.html delete mode 100644 doc/manpage.d/ipsec__copyright.8.html delete mode 100644 doc/manpage.d/ipsec__include.8.html delete mode 100644 doc/manpage.d/ipsec__keycensor.8.html delete mode 100644 doc/manpage.d/ipsec__plutoload.8.html delete mode 100644 doc/manpage.d/ipsec__plutorun.8.html delete mode 100644 doc/manpage.d/ipsec__realsetup.8.html delete mode 100644 doc/manpage.d/ipsec__secretcensor.8.html delete mode 100644 doc/manpage.d/ipsec__startklips.8.html delete mode 100644 doc/manpage.d/ipsec__updown.8.html delete mode 100644 doc/manpage.d/ipsec_addrbytesof.3.html delete mode 100644 doc/manpage.d/ipsec_addrbytesptr.3.html delete mode 100644 doc/manpage.d/ipsec_addrcmp.3.html delete mode 100644 doc/manpage.d/ipsec_addrinsubnet.3.html delete mode 100644 doc/manpage.d/ipsec_addrlenof.3.html delete mode 100644 doc/manpage.d/ipsec_addrtoa.3.html delete mode 100644 doc/manpage.d/ipsec_addrtosubnet.3.html delete mode 100644 doc/manpage.d/ipsec_addrtot.3.html delete mode 100644 doc/manpage.d/ipsec_addrtypeof.3.html delete mode 100644 doc/manpage.d/ipsec_anyaddr.3.html delete mode 100644 doc/manpage.d/ipsec_atoaddr.3.html delete mode 100644 doc/manpage.d/ipsec_atoasr.3.html delete mode 100644 doc/manpage.d/ipsec_atosa.3.html delete mode 100644 doc/manpage.d/ipsec_atosubnet.3.html delete mode 100644 doc/manpage.d/ipsec_atoul.3.html delete mode 100644 doc/manpage.d/ipsec_auto.8.html delete mode 100644 doc/manpage.d/ipsec_barf.8.html delete mode 100644 doc/manpage.d/ipsec_bitstomask.3.html delete mode 100644 doc/manpage.d/ipsec_broadcastof.3.html delete mode 100644 doc/manpage.d/ipsec_calcgoo.8.html delete mode 100644 doc/manpage.d/ipsec_copyright_notice.3.html delete mode 100644 doc/manpage.d/ipsec_datatot.3.html delete mode 100644 doc/manpage.d/ipsec_eroute.5.html delete mode 100644 doc/manpage.d/ipsec_eroute.8.html delete mode 100644 doc/manpage.d/ipsec_goodmask.3.html delete mode 100644 doc/manpage.d/ipsec_hostof.3.html delete mode 100644 doc/manpage.d/ipsec_ikeping.8.html delete mode 100644 doc/manpage.d/ipsec_initaddr.3.html delete mode 100644 doc/manpage.d/ipsec_initsaid.3.html delete mode 100644 doc/manpage.d/ipsec_initsubnet.3.html delete mode 100644 doc/manpage.d/ipsec_isanyaddr.3.html delete mode 100644 doc/manpage.d/ipsec_isloopbackaddr.3.html delete mode 100644 doc/manpage.d/ipsec_isunspecaddr.3.html delete mode 100644 doc/manpage.d/ipsec_keyblobtoid.3.html delete mode 100644 doc/manpage.d/ipsec_klipsdebug.5.html delete mode 100644 doc/manpage.d/ipsec_klipsdebug.8.html delete mode 100644 doc/manpage.d/ipsec_look.8.html delete mode 100644 doc/manpage.d/ipsec_loopbackaddr.3.html delete mode 100644 doc/manpage.d/ipsec_lwdnsq.8.html delete mode 100644 doc/manpage.d/ipsec_mailkey.8.html delete mode 100644 doc/manpage.d/ipsec_manual.8.html delete mode 100644 doc/manpage.d/ipsec_maskof.3.html delete mode 100644 doc/manpage.d/ipsec_masktobits.3.html delete mode 100644 doc/manpage.d/ipsec_masktocount.3.html delete mode 100644 doc/manpage.d/ipsec_networkof.3.html delete mode 100644 doc/manpage.d/ipsec_newhostkey.8.html delete mode 100644 doc/manpage.d/ipsec_optionsfrom.3.html delete mode 100644 doc/manpage.d/ipsec_pf_key.5.html delete mode 100644 doc/manpage.d/ipsec_pf_key.8.html delete mode 100644 doc/manpage.d/ipsec_pluto.8.html delete mode 100644 doc/manpage.d/ipsec_portof.3.html delete mode 100644 doc/manpage.d/ipsec_prng.3.html delete mode 100644 doc/manpage.d/ipsec_prng_bytes.3.html delete mode 100644 doc/manpage.d/ipsec_prng_final.3.html delete mode 100644 doc/manpage.d/ipsec_prng_init.3.html delete mode 100644 doc/manpage.d/ipsec_ranbits.8.html delete mode 100644 doc/manpage.d/ipsec_rangetoa.3.html delete mode 100644 doc/manpage.d/ipsec_rangetosubnet.3.html delete mode 100644 doc/manpage.d/ipsec_rsasigkey.8.html delete mode 100644 doc/manpage.d/ipsec_sameaddr.3.html delete mode 100644 doc/manpage.d/ipsec_sameaddrtype.3.html delete mode 100644 doc/manpage.d/ipsec_samesaid.3.html delete mode 100644 doc/manpage.d/ipsec_samesubnet.3.html delete mode 100644 doc/manpage.d/ipsec_samesubnettype.3.html delete mode 100644 doc/manpage.d/ipsec_satoa.3.html delete mode 100644 doc/manpage.d/ipsec_satot.3.html delete mode 100644 doc/manpage.d/ipsec_send-pr.8.html delete mode 100644 doc/manpage.d/ipsec_setportof.3.html delete mode 100644 doc/manpage.d/ipsec_setup.8.html delete mode 100644 doc/manpage.d/ipsec_showdefaults.8.html delete mode 100644 doc/manpage.d/ipsec_showhostkey.8.html delete mode 100644 doc/manpage.d/ipsec_showpolicy.8.html delete mode 100644 doc/manpage.d/ipsec_sockaddrlenof.3.html delete mode 100644 doc/manpage.d/ipsec_sockaddrof.3.html delete mode 100644 doc/manpage.d/ipsec_spi.5.html delete mode 100644 doc/manpage.d/ipsec_spi.8.html delete mode 100644 doc/manpage.d/ipsec_spigrp.5.html delete mode 100644 doc/manpage.d/ipsec_spigrp.8.html delete mode 100644 doc/manpage.d/ipsec_splitkeytoid.3.html delete mode 100644 doc/manpage.d/ipsec_subnetinsubnet.3.html delete mode 100644 doc/manpage.d/ipsec_subnetishost.3.html delete mode 100644 doc/manpage.d/ipsec_subnetof.3.html delete mode 100644 doc/manpage.d/ipsec_subnettoa.3.html delete mode 100644 doc/manpage.d/ipsec_subnettot.3.html delete mode 100644 doc/manpage.d/ipsec_subnettypeof.3.html delete mode 100644 doc/manpage.d/ipsec_tnatoaddr.3.html delete mode 100644 doc/manpage.d/ipsec_tncfg.5.html delete mode 100644 doc/manpage.d/ipsec_tncfg.8.html delete mode 100644 doc/manpage.d/ipsec_trap_count.5.html delete mode 100644 doc/manpage.d/ipsec_trap_sendcount.5.html delete mode 100644 doc/manpage.d/ipsec_ttoaddr.3.html delete mode 100644 doc/manpage.d/ipsec_ttodata.3.html delete mode 100644 doc/manpage.d/ipsec_ttosa.3.html delete mode 100644 doc/manpage.d/ipsec_ttosubnet.3.html delete mode 100644 doc/manpage.d/ipsec_ttoul.3.html delete mode 100644 doc/manpage.d/ipsec_ultoa.3.html delete mode 100644 doc/manpage.d/ipsec_ultot.3.html delete mode 100644 doc/manpage.d/ipsec_unspecaddr.3.html delete mode 100644 doc/manpage.d/ipsec_verify.8.html delete mode 100644 doc/manpage.d/ipsec_version.3.html delete mode 100644 doc/manpage.d/ipsec_version.5.html delete mode 100644 doc/manpage.d/ipsec_version_code.3.html delete mode 100644 doc/manpage.d/ipsec_version_string.3.html delete mode 100644 doc/manpage.d/ipsec_whack.8.html delete mode 100644 doc/src/draft-richardson-ipsec-opportunistic.html delete mode 100644 doc/src/draft-richardson-ipsec-opportunistic.xml delete mode 100644 doc/src/draft-richardson-ipsec-rr.html delete mode 100644 doc/src/draft-richardson-ipsec-rr.xml (limited to 'doc') diff --git a/doc/draft-richardson-ipsec-opportunistic.txt b/doc/draft-richardson-ipsec-opportunistic.txt deleted file mode 100644 index 4c87d857a..000000000 --- a/doc/draft-richardson-ipsec-opportunistic.txt +++ /dev/null @@ -1,2688 +0,0 @@ - - -Independent submission M. Richardson -Internet-Draft SSW -Expires: November 19, 2003 D. Redelmeier - Mimosa - May 21, 2003 - - - Opportunistic Encryption using The Internet Key Exchange (IKE) - draft-richardson-ipsec-opportunistic-11.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on November 19, 2003. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This document describes opportunistic encryption (OE) using the - Internet Key Exchange (IKE) and IPsec. Each system administrator - adds new resource records to his or her Domain Name System (DNS) to - support opportunistic encryption. The objective is to allow - encryption for secure communication without any pre-arrangement - specific to the pair of systems involved. - - DNS is used to distribute the public keys of each system involved. - This is resistant to passive attacks. The use of DNS Security - (DNSSEC) secures this system against active attackers as well. - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 1] - -Internet-Draft opportunistic May 2003 - - - As a result, the administrative overhead is reduced from the square - of the number of systems to a linear dependence, and it becomes - possible to make secure communication the default even when the - partner is not known in advance. - - This document is offered up as an Informational RFC. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 10 - 4. Impacts on IKE . . . . . . . . . . . . . . . . . . . . . . . . 21 - 5. DNS issues . . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 6. Network address translation interaction . . . . . . . . . . . 28 - 7. Host implementations . . . . . . . . . . . . . . . . . . . . . 29 - 8. Multi-homing . . . . . . . . . . . . . . . . . . . . . . . . . 30 - 9. Failure modes . . . . . . . . . . . . . . . . . . . . . . . . 32 - 10. Unresolved issues . . . . . . . . . . . . . . . . . . . . . . 34 - 11. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 - 12. Security considerations . . . . . . . . . . . . . . . . . . . 42 - 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 44 - 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 - Normative references . . . . . . . . . . . . . . . . . . . . . 46 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 47 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . 48 - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 2] - -Internet-Draft opportunistic May 2003 - - -1. Introduction - -1.1 Motivation - - The objective of opportunistic encryption is to allow encryption - without any pre-arrangement specific to the pair of systems involved. - Each system administrator adds public key information to DNS records - to support opportunistic encryption and then enables this feature in - the nodes' IPsec stack. Once this is done, any two such nodes can - communicate securely. - - This document describes opportunistic encryption as designed and - mostly implemented by the Linux FreeS/WAN project. For project - information, see http://www.freeswan.org. - - The Internet Architecture Board (IAB) and Internet Engineering - Steering Group (IESG) have taken a strong stand that the Internet - should use powerful encryption to provide security and privacy [4]. - The Linux FreeS/WAN project attempts to provide a practical means to - implement this policy. - - The project uses the IPsec, ISAKMP/IKE, DNS and DNSSEC protocols - because they are standardized, widely available and can often be - deployed very easily without changing hardware or software or - retraining users. - - The extensions to support opportunistic encryption are simple. No - changes to any on-the-wire formats are needed. The only changes are - to the policy decision making system. This means that opportunistic - encryption can be implemented with very minimal changes to an - existing IPsec implementation. - - Opportunistic encryption creates a "fax effect". The proliferation - of the fax machine was possible because it did not require that - everyone buy one overnight. Instead, as each person installed one, - the value of having one increased - as there were more people that - could receive faxes. Once opportunistic encryption is installed it - automatically recognizes other boxes using opportunistic encryption, - without any further configuration by the network administrator. So, - as opportunistic encryption software is installed on more boxes, its - value as a tool increases. - - This document describes the infrastructure to permit deployment of - Opportunistic Encryption. - - The term S/WAN is a trademark of RSA Data Systems, and is used with - permission by this project. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 3] - -Internet-Draft opportunistic May 2003 - - -1.2 Types of network traffic - - To aid in understanding the relationship between security processing - and IPsec we divide network traffic into four categories: - - * Deny: networks to which traffic is always forbidden. - - * Permit: networks to which traffic in the clear is permitted. - - * Opportunistic tunnel: networks to which traffic is encrypted if - possible, but otherwise is in the clear or fails depending on the - default policy in place. - - * Configured tunnel: networks to which traffic must be encrypted, and - traffic in the clear is never permitted. - - Traditional firewall devices handle the first two categories. No - authentication is required. The permit policy is currently the - default on the Internet. - - This document describes the third category - opportunistic tunnel, - which is proposed as the new default for the Internet. - - Category four, encrypt traffic or drop it, requires authentication of - the end points. As the number of end points is typically bounded and - is typically under a single authority, arranging for distribution of - authentication material, while difficult, does not require any new - technology. The mechanism described here provides an additional way - to distribute the authentication materials, that of a public key - method that does not require deployment of an X.509 based - infrastructure. - - Current Virtual Private Networks can often be replaced by an "OE - paranoid" policy as described herein. - -1.3 Peer authentication in opportunistic encryption - - Opportunistic encryption creates tunnels between nodes that are - essentially strangers. This is done without any prior bilateral - arrangement. There is, therefore, the difficult question of how one - knows to whom one is talking. - - One possible answer is that since no useful authentication can be - done, none should be tried. This mode of operation is named - "anonymous encryption". An active man-in-the-middle attack can be - used to thwart the privacy of this type of communication. Without - peer authentication, there is no way to prevent this kind of attack. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 4] - -Internet-Draft opportunistic May 2003 - - - Although a useful mode, anonymous encryption is not the goal of this - project. Simpler methods are available that can achieve anonymous - encryption only, but authentication of the peer is a desireable goal. - The latter is achieved through key distribution in DNS, leveraging - upon the authentication of the DNS in DNSSEC. - - Peers are, therefore, authenticated with DNSSEC when available. - Local policy determines how much trust to extend when DNSSEC is not - available. - - However, an essential premise of building private connections with - strangers is that datagrams received through opportunistic tunnels - are no more special than datagrams that arrive in the clear. Unlike - in a VPN, these datagrams should not be given any special exceptions - when it comes to auditing, further authentication or firewalling. - - When initiating outbound opportunistic encryption, local - configuration determines what happens if tunnel setup fails. It may - be that the packet goes out in the clear, or it may be dropped. - -1.4 Use of RFC2119 terms - - The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, - SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this - document, are to be interpreted as described in [5] - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 5] - -Internet-Draft opportunistic May 2003 - - -2. Overview - -2.1 Reference diagram - - --------------------------------------------------------------------- - - The following network diagram is used in the rest of this document as - the canonical diagram: - - [Q] [R] - . . AS2 - [A]----+----[SG-A].......+....+.......[SG-B]-------[B] - | ...... - AS1 | ..PI.. - | ...... - [D]----+----[SG-D].......+....+.......[C] AS3 - - - - Figure 1: Reference Network Diagram - - --------------------------------------------------------------------- - - In this diagram, there are four end-nodes: A, B, C and D. There are - three gateways, SG-A, SG-B, SG-D. A, D, SG-A and SG-D are part of - the same administrative authority, AS1. SG-A and SG-D are on two - different exit paths from organization 1. SG-B/B is an independent - organization, AS2. Nodes Q and R are nodes on the Internet. PI is - the Public Internet ("The Wild"). - -2.2 Terminology - - The following terminology is used in this document: - - Security gateway: a system that performs IPsec tunnel mode - encapsulation/decapsulation. [SG-x] in the diagram. - - Alice: node [A] in the diagram. When an IP address is needed, this - is 192.1.0.65. - - Bob: node [B] in the diagram. When an IP address is needed, this is - 192.2.0.66. - - Carol: node [C] in the diagram. When an IP address is needed, this - is 192.1.1.67. - - Dave: node [D] in the diagram. When an IP address is needed, this is - 192.3.0.68. - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 6] - -Internet-Draft opportunistic May 2003 - - - SG-A: Alice's security gateway. Internally it is 192.1.0.1, - externally it is 192.1.1.4. - - SG-B: Bob's security gateway. Internally it is 192.2.0.1, externally - it is 192.1.1.5. - - SG-D: Dave's security gateway. Also Alice's backup security gateway. - Internally it is 192.3.0.1, externally it is 192.1.1.6. - - - A single dash represents clear-text datagrams. - - = An equals sign represents phase 2 (IPsec) cipher-text datagrams. - - ~ A single tilde represents clear-text phase 1 datagrams. - - # A hash sign represents phase 1 (IKE) cipher-text datagrams. - - . A period represents an untrusted network of unknown type. - - Configured tunnel: a tunnel that is directly and deliberately hand - configured on participating gateways. Configured tunnels are - typically given a higher level of trust than opportunistic - tunnels. - - Road warrior tunnel: a configured tunnel connecting one node with a - fixed IP address and one node with a variable IP address. A road - warrior (RW) connection must be initiated by the variable node, - since the fixed node cannot know the current address for the road - warrior. - - Anonymous encryption: the process of encrypting a session without any - knowledge of who the other parties are. No authentication of - identities is done. - - Opportunistic encryption: the process of encrypting a session with - authenticated knowledge of who the other parties are. - - Lifetime: the period in seconds (bytes or datagrams) for which a - security association will remain alive before needing to be re- - keyed. - - Lifespan: the effective time for which a security association remains - useful. A security association with a lifespan shorter than its - lifetime would be removed when no longer needed. A security - association with a lifespan longer than its lifetime would need to - be re-keyed one or more times. - - Phase 1 SA: an ISAKMP/IKE security association sometimes referred to - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 7] - -Internet-Draft opportunistic May 2003 - - - as a keying channel. - - Phase 2 SA: an IPsec security association. - - Tunnel: another term for a set of phase 2 SA (one in each direction). - - NAT: Network Address Translation (see [20]). - - NAPT: Network Address and Port Translation (see [20]). - - AS: an autonomous system (AS) is a group of systems (a network) that - are under the administrative control of a single organization. - - Default-free zone: a set of routers that maintain a complete set of - routes to all currently reachable destinations. Having such a - list, these routers never make use of a default route. A datagram - with a destination address not matching any route will be dropped - by such a router. - - -2.3 Model of operation - - The opportunistic encryption security gateway (OE gateway) is a - regular gateway node as described in [2] section 2.4 and [3] with the - additional capabilities described here and in [7]. The algorithm - described here provides a way to determine, for each datagram, - whether or not to encrypt and tunnel the datagram. Two important - things that must be determined are whether or not to encrypt and - tunnel and, if so, the destination address or name of the tunnel end - point which should be used. - -2.3.1 Tunnel authorization - - The OE gateway determines whether or not to create a tunnel based on - the destination address of each packet. Upon receiving a packet with - a destination address not recently seen, the OE gateway performs a - lookup in DNS for an authorization resource record (see Section 5.2). - The record is located using the IP address to perform a search in the - in-addr.arpa (IPv4) or ip6.arpa (IPv6) maps. If an authorization - record is found, the OE gateway interprets this as a request for a - tunnel to be formed. - -2.3.2 Tunnel end-point discovery - - The authorization resource record also provides the address or name - of the tunnel end point which should be used. - - The record may also provide the public RSA key of the tunnel end - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 8] - -Internet-Draft opportunistic May 2003 - - - point itself. This is provided for efficiency only. If the public - RSA key is not present, the OE gateway performs a second lookup to - find a KEY resource record for the end point address or name. - - Origin and integrity protection of the resource records is provided - by DNSSEC ([16]). Section 3.2.4.1 documents an optional restriction - on the tunnel end point if DNSSEC signatures are not available for - the relevant records. - -2.3.3 Caching of authorization results - - The OE gateway maintains a cache, in the forwarding plane, of source/ - destination pairs for which opportunistic encryption has been - attempted. This cache maintains a record of whether or not OE was - successful so that subsequent datagrams can be forwarded properly - without additional delay. - - Successful negotiation of OE instantiates a new security association. - Failure to negotiate OE results in creation of a forwarding policy - entry either to drop or transmit in the clear future datagrams. This - negative cache is necessary to avoid the possibly lengthy process of - repeatedly looking up the same information. - - The cache is timed out periodically, as described in Section 3.4. - This removes entries that are no longer being used and permits the - discovery of changes in authorization policy. - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 9] - -Internet-Draft opportunistic May 2003 - - -3. Specification - - The OE gateway is modeled to have a forwarding plane and a control - plane. A control channel, such as PF_KEY, connects the two planes. - (See [6].) The forwarding plane performs per datagram operations. - The control plane contains a keying daemon, such as ISAKMP/IKE, and - performs all authorization, peer authentication and key derivation - functions. - -3.1 Datagram state machine - - Let the OE gateway maintain a collection of objects -- a superset of - the security policy database (SPD) specified in [7]. For each - combination of source and destination address, an SPD object exists - in one of five following states. Prior to forwarding each datagram, - the responder uses the source and destination addresses to pick an - entry from the SPD. The SPD then determines if and how the packet is - forwarded. - -3.1.1 Non-existent policy - - If the responder does not find an entry, then this policy applies. - The responder creates an entry with an initial state of "hold policy" - and requests keying material from the keying daemon. The responder - does not forward the datagram, rather it attaches the datagram to the - SPD entry as the "first" datagram and retains it for eventual - transmission in a new state. - -3.1.2 Hold policy - - The responder requests keying material. If the interface to the - keying system is lossy (PF_KEY, for instance, can be), the - implementation SHOULD include a mechanism to retransmit the keying - request at a rate limited to less than 1 request per second. The - responder does not forward the datagram. It attaches the datagram to - the SPD entry as the "last" datagram where it is retained for - eventual transmission. If there is a datagram already so stored, - then that already stored datagram is discarded. - - Because the "first" datagram is probably a TCP SYN packet, the - responder retains the "first" datagram in an attempt to avoid waiting - for a TCP retransmit. The responder retains the "last" datagram in - deference to streaming protocols that find it useful to know how much - data has been lost. These are recommendations to decrease latency. - There are no operational requirements for this. - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 10] - -Internet-Draft opportunistic May 2003 - - -3.1.3 Pass-through policy - - The responder forwards the datagram using the normal forwarding - table. The responder enters this state only by command from the - keying daemon, and upon entering this state, also forwards the - "first" and "last" datagrams. - -3.1.4 Deny policy - - The responder discards the datagram. The responder enters this state - only by command from the keying daemon, and upon entering this state, - discards the "first" and "last" datagrams. Local administration - decides if further datagrams cause ICMP messages to be generated - (i.e. ICMP Destination Unreachable, Communication Administratively - Prohibited. type=3, code=13). - -3.1.5 Encrypt policy - - The responder encrypts the datagram using the indicated security - association database (SAD) entry. The responder enters this state - only by command from the keying daemon, and upon entering this state, - releases and forwards the "first" and "last" datagrams using the new - encrypt policy. - - If the associated SAD entry expires because of byte, packet or time - limits, then the entry returns to the Hold policy, and an expire - message is sent to the keying daemon. - - All states may be created directly by the keying daemon while acting - as a responder. - -3.2 Keying state machine - initiator - - Let the keying daemon maintain a collection of objects. Let them be - called "connections" or "conn"s. There are two categories of - connection objects: classes and instances. A class represents an - abstract policy - what could be. An instance represents an actual - connection - what is implemented at the time. - - Let there be two further subtypes of connections: keying channels - (Phase 1 SAs) and data channels (Phase 2 SAs). Each data channel - object may have a corresponding SPD and SAD entry maintained by the - datagram state machine. - - For the purposes of opportunistic encryption, there MUST, at least, - be connection classes known as "deny", "always-clear-text", "OE- - permissive", and "OE-paranoid". The latter two connection classes - define a set of source and/or destination addresses for which - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 11] - -Internet-Draft opportunistic May 2003 - - - opportunistic encryption will be attempted. The administrator MAY - set policy options in a number of additional places. An - implementation MAY create additional connection classes to further - refine these policies. - - The simplest system may need only the "OE-permissive" connection, and - would list its own (single) IP address as the source address of this - policy and the wild-card address 0.0.0.0/0 as the destination IPv4 - address. That is, the simplest policy is to try opportunistic - encryption with all destinations. - - The distinction between permissive and paranoid OE use will become - clear in the state transition differences. In general a permissive - OE will, on failure, install a pass-through policy, while a paranoid - OE will, on failure, install a drop policy. - - In this description of the keying machine's state transitions, the - states associated with the keying system itself are omitted because - they are best documented in the keying system ([8], [9] and [10] for - ISAKMP/IKE), and the details are keying system specific. - Opportunistic encryption is not dependent upon any specific keying - protocol, but this document does provide requirements for those using - ISAKMP/IKE to assure that implementations inter-operate. - - The state transitions that may be involved in communicating with the - forwarding plane are omitted. PF_KEY and similar protocols have - their own set of states required for message sends and completion - notifications. - - Finally, the retransmits and recursive lookups that are normal for - DNS are not included in this description of the state machine. - -3.2.1 Nonexistent connection - - There is no connection instance for a given source/destination - address pair. Upon receipt of a request for keying material for this - source/destination pair, the initiator searches through the - connection classes to determine the most appropriate policy. Upon - determining an appropriate connection class, an instance object is - created of that type. Both of the OE types result in a potential OE - connection. - - Failure to find an appropriate connection class results in an - administrator defined default. - - In each case, when the initiator finds an appropriate class for the - new flow, an instance connection is made of the class which matched. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 12] - -Internet-Draft opportunistic May 2003 - - -3.2.2 Clear-text connection - - The non-existent connection makes a transition to this state when an - always-clear-text class is instantiated, or when an OE-permissive - connection fails. During the transition, the initiator creates a - pass-through policy object in the forwarding plane for the - appropriate flow. - - Timing out is the only way to leave this state (see Section 3.2.7). - -3.2.3 Deny connection - - The empty connection makes a transition to this state when a deny - class is instantiated, or when an OE-paranoid connection fails. - During the transition, the initiator creates a deny policy object in - the forwarding plane for the appropriate flow. - - Timing out is the only way to leave this state (see Section 3.2.7). - -3.2.4 Potential OE connection - - The empty connection makes a transition to this state when one of - either OE class is instantiated. During the transition to this - state, the initiator creates a hold policy object in the forwarding - plane for the appropriate flow. - - In addition, when making a transition into this state, DNS lookup is - done in the reverse-map for a TXT delegation resource record (see - Section 5.2). The lookup key is the destination address of the flow. - - There are three ways to exit this state: - - 1. DNS lookup finds a TXT delegation resource record. - - 2. DNS lookup does not find a TXT delegation resource record. - - 3. DNS lookup times out. - - Based upon the results of the DNS lookup, the potential OE connection - makes a transition to the pending OE connection state. The - conditions for a successful DNS look are: - - 1. DNS finds an appropriate resource record - - 2. It is properly formatted according to Section 5.2 - - 3. if DNSSEC is enabled, then the signature has been vouched for. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 13] - -Internet-Draft opportunistic May 2003 - - - Note that if the initiator does not find the public key present in - the TXT delegation record, then the public key must be looked up as a - sub-state. Only successful completion of all the DNS lookups is - considered a success. - - If DNS lookup does not find a resource record or DNS times out, then - the initiator considers the receiver not OE capable. If this is an - OE-paranoid instance, then the potential OE connection makes a - transition to the deny connection state. If this is an OE-permissive - instance, then the potential OE connection makes a transition to the - clear-text connection state. - - If the initiator finds a resource record but it is not properly - formatted, or if DNSSEC is enabled and reports a failure to - authenticate, then the potential OE connection should make a - transition to the deny connection state. This action SHOULD be - logged. If the administrator wishes to override this transition - between states, then an always-clear class can be installed for this - flow. An implementation MAY make this situation a new class. - -3.2.4.1 Restriction on unauthenticated TXT delegation records - - An implementation SHOULD also provide an additional administrative - control on delegation records and DNSSEC. This control would apply - to delegation records (the TXT records in the reverse-map) that are - not protected by DNSSEC. Records of this type are only permitted to - delegate to their own address as a gateway. When this option is - enabled, an active attack on DNS will be unable to redirect packets - to other than the original destination. - -3.2.5 Pending OE connection - - The potential OE connection makes a transition to this state when the - initiator determines that all the information required from the DNS - lookup is present. Upon entering this state, the initiator attempts - to initiate keying to the gateway provided. - - Exit from this state occurs either with a successfully created IPsec - SA, or with a failure of some kind. Successful SA creation results - in a transition to the key connection state. - - Three failures have caused significant problems. They are clearly - not the only possible failures from keying. - - Note that if there are multiple gateways available in the TXT - delegation records, then a failure can only be declared after all - have been tried. Further, creation of a phase 1 SA does not - constitute success. A set of phase 2 SAs (a tunnel) is considered - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 14] - -Internet-Draft opportunistic May 2003 - - - success. - - The first failure occurs when an ICMP port unreachable is - consistently received without any other communication, or when there - is silence from the remote end. This usually means that either the - gateway is not alive, or the keying daemon is not functional. For an - OE-permissive connection, the initiator makes a transition to the - clear-text connection but with a low lifespan. For an OE-pessimistic - connection, the initiator makes a transition to the deny connection - again with a low lifespan. The lifespan in both cases is kept low - because the remote gateway may be in the process of rebooting or be - otherwise temporarily unavailable. - - The length of time to wait for the remote keying daemon to wake up is - a matter of some debate. If there is a routing failure, 5 minutes is - usually long enough for the network to re-converge. Many systems can - reboot in that amount of time as well. However, 5 minutes is far too - long for most users to wait to hear that they can not connect using - OE. Implementations SHOULD make this a tunable parameter. - - The second failure occurs after a phase 1 SA has been created, but - there is either no response to the phase 2 proposal, or the initiator - receives a negative notify (the notify must be authenticated). The - remote gateway is not prepared to do OE at this time. As before, the - initiator makes a transition to the clear-text or the deny connection - based upon connection class, but this time with a normal lifespan. - - The third failure occurs when there is signature failure while - authenticating the remote gateway. This can occur when there has - been a key roll-over, but DNS has not caught up. In this case again, - the initiator makes a transition to the clear-text or the deny - connection based upon the connection class. However, the lifespan - depends upon the remaining time to live in the DNS. (Note that - DNSSEC signed resource records have a different expiry time than non- - signed records.) - -3.2.6 Keyed connection - - The pending OE connection makes a transition to this state when - session keying material (the phase 2 SAs) is derived. The initiator - creates an encrypt policy in the forwarding plane for this flow. - - There are three ways to exit this state. The first is by receipt of - an authenticated delete message (via the keying channel) from the - peer. This is normal teardown and results in a transition to the - expired connection state. - - The second exit is by expiry of the forwarding plane keying material. - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 15] - -Internet-Draft opportunistic May 2003 - - - This starts a re-key operation with a transition back to pending OE - connection. In general, the soft expiry occurs with sufficient time - left to continue to use the keys. A re-key can fail, which may - result in the connection failing to clear-text or deny as - appropriate. In the event of a failure, the forwarding plane policy - does not change until the phase 2 SA (IPsec SA) reaches its hard - expiry. - - The third exit is in response to a negotiation from a remote gateway. - If the forwarding plane signals the control plane that it has - received an unknown SPI from the remote gateway, or an ICMP is - received from the remote gateway indicating an unknown SPI, the - initiator should consider that the remote gateway has rebooted or - restarted. Since these indications are easily forged, the - implementation must exercise care. The initiator should make a - cautious (rate-limited) attempt to re-key the connection. - -3.2.7 Expiring connection - - The initiator will periodically place each of the deny, clear-text, - and keyed connections into this sub-state. See Section 3.4 for more - details of how often this occurs. The initiator queries the - forwarding plane for last use time of the appropriate policy. If the - last use time is relatively recent, then the connection returns to - the previous deny, clear-text or keyed connection state. If not, - then the connection enters the expired connection state. - - The DNS query and answer that lead to the expiring connection state - are also examined. The DNS query may become stale. (A negative, - i.e. no such record, answer is valid for the period of time given by - the MINIMUM field in an attached SOA record. See [12] section - 4.3.4.) If the DNS query is stale, then a new query is made. If the - results change, then the connection makes a transition to a new state - as described in potential OE connection state. - - Note that when considering how stale a connection is, both outgoing - SPD and incoming SAD must be queried as some flows may be - unidirectional for some time. - - Also note that the policy at the forwarding plane is not updated - unless there is a conclusion that there should be a change. - -3.2.8 Expired connection - - Entry to this state occurs when no datagrams have been forwarded - recently via the appropriate SPD and SAD objects. The objects in the - forwarding plane are removed (logging any final byte and packet - counts if appropriate) and the connection instance in the keying - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 16] - -Internet-Draft opportunistic May 2003 - - - plane is deleted. - - The initiator sends an ISAKMP/IKE delete to clean up the phase 2 SAs - as described in Section 3.4. - - Whether or not to delete the phase 1 SAs at this time is left as a - local implementation issue. Implementations that do delete the phase - 1 SAs MUST send authenticated delete messages to indicate that they - are doing so. There is an advantage to keeping the phase 1 SAs until - they expire - they may prove useful again in the near future. - -3.3 Keying state machine - responder - - The responder has a set of objects identical to those of the - initiator. - - The responder receives an invitation to create a keying channel from - an initiator. - -3.3.1 Unauthenticated OE peer - - Upon entering this state, the responder starts a DNS lookup for a KEY - record for the initiator. The responder looks in the reverse-map for - a KEY record for the initiator if the initiator has offered an - ID_IPV4_ADDR, and in the forward map if the initiator has offered an - ID_FQDN type. (See [8] section 4.6.2.1.) - - The responder exits this state upon successful receipt of a KEY from - DNS, and use of the key to verify the signature of the initiator. - - Successful authentication of the peer results in a transition to the - authenticated OE Peer state. - - Note that the unauthenticated OE peer state generally occurs in the - middle of the key negotiation protocol. It is really a form of - pseudo-state. - -3.3.2 Authenticated OE Peer - - The peer will eventually propose one or more phase 2 SAs. The - responder uses the source and destination address in the proposal to - finish instantiating the connection state using the connection class - table. The responder MUST search for an identical connection object - at this point. - - If an identical connection is found, then the responder deletes the - old instance, and the new object makes a transition to the pending OE - connection state. This means that new ISAKMP connections with a - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 17] - -Internet-Draft opportunistic May 2003 - - - given peer will always use the latest instance, which is the correct - one if the peer has rebooted in the interim. - - If an identical connection is not found, then the responder makes the - transition according to the rules given for the initiator. - - Note that if the initiator is in OE-paranoid mode and the responder - is in either always-clear-text or deny, then no communication is - possible according to policy. An implementation is permitted to - create new types of policies such as "accept OE but do not initiate - it". This is a local matter. - -3.4 Renewal and teardown - -3.4.1 Aging - - A potentially unlimited number of tunnels may exist. In practice, - only a few tunnels are used during a period of time. Unused tunnels - MUST, therefore, be torn down. Detecting when tunnels are no longer - in use is the subject of this section. - - There are two methods for removing tunnels: explicit deletion or - expiry. - - Explicit deletion requires an IKE delete message. As the deletes - MUST be authenticated, both ends of the tunnel must maintain the key - channel (phase 1 ISAKMP SA). An implementation which refuses to - either maintain or recreate the keying channel SA will be unable to - use this method. - - The tunnel expiry method, simply allows the IKE daemon to expire - normally without attempting to re-key it. - - Regardless of which method is used to remove tunnels, the - implementation requires a method to determine if the tunnel is still - in use. The specifics are a local matter, but the FreeS/WAN project - uses the following criteria. These criteria are currently - implemented in the key management daemon, but could also be - implemented at the SPD layer using an idle timer. - - Set a short initial (soft) lifespan of 1 minute since many net flows - last only a few seconds. - - At the end of the lifespan, check to see if the tunnel was used by - traffic in either direction during the last 30 seconds. If so, - assign a longer tentative lifespan of 20 minutes after which, look - again. If the tunnel is not in use, then close the tunnel. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 18] - -Internet-Draft opportunistic May 2003 - - - The expiring state in the key management system (see Section 3.2.7) - implements these timeouts. The timer above may be in the forwarding - plane, but then it must be re-settable. - - The tentative lifespan is independent of re-keying; it is just the - time when the tunnel's future is next considered. (The term lifespan - is used here rather than lifetime for this reason.) Unlike re-keying, - this tunnel use check is not costly and should happen reasonably - frequently. - - A multi-step back-off algorithm is not considered worth the effort - here. - - If the security gateway and the client host are the same and not a - Bump-in-the-Stack or Bump-in-the-Wire implementation, tunnel teardown - decisions MAY pay attention to TCP connection status as reported by - the local TCP layer. A still-open TCP connection is almost a - guarantee that more traffic is expected. Closing of the only TCP - connection through a tunnel is a strong hint that no more traffic is - expected. - -3.4.2 Teardown and cleanup - - Teardown should always be coordinated between the two ends of the - tunnel by interpreting and sending delete notifications. There is a - detailed sub-state in the expired connection state of the key manager - that relates to retransmits of the delete notifications, but this is - considered to be a keying system detail. - - On receiving a delete for the outbound SAs of a tunnel (or some - subset of them), tear down the inbound ones also and notify the - remote end with a delete. If the local system receives a delete for - a tunnel which is no longer in existence, then two delete messages - have crossed paths. Ignore the delete. The operation has already - been completed. Do not generate any messages in this situation. - - Tunnels are to be considered as bidirectional entities, even though - the low-level protocols don't treat them this way. - - When the deletion is initiated locally, rather than as a response to - a received delete, send a delete for (all) the inbound SAs of a - tunnel. If the local system does not receive a responding delete for - the outbound SAs, try re-sending the original delete. Three tries - spaced 10 seconds apart seems a reasonable level of effort. A - failure of the other end to respond after 3 attempts, indicates that - the possibility of further communication is unlikely. Remove the - outgoing SAs. (The remote system may be a mobile node that is no - longer present or powered on.) - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 19] - -Internet-Draft opportunistic May 2003 - - - After re-keying, transmission should switch to using the new outgoing - SAs (ISAKMP or IPsec) immediately, and the old leftover outgoing SAs - should be cleared out promptly (delete should be sent for the - outgoing SAs) rather than waiting for them to expire. This reduces - clutter and minimizes confusion for the operator doing diagnostics. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 20] - -Internet-Draft opportunistic May 2003 - - -4. Impacts on IKE - -4.1 ISAKMP/IKE protocol - - The IKE wire protocol needs no modifications. The major changes are - implementation issues relating to how the proposals are interpreted, - and from whom they may come. - - As opportunistic encryption is designed to be useful between peers - without prior operator configuration, an IKE daemon must be prepared - to negotiate phase 1 SAs with any node. This may require a large - amount of resources to maintain cookie state, as well as large - amounts of entropy for nonces, cookies and so on. - - The major changes to support opportunistic encryption are at the IKE - daemon level. These changes relate to handling of key acquisition - requests, lookup of public keys and TXT records, and interactions - with firewalls and other security facilities that may be co-resident - on the same gateway. - -4.2 Gateway discovery process - - In a typical configured tunnel, the address of SG-B is provided via - configuration. Furthermore, the mapping of an SPD entry to a gateway - is typically a 1:1 mapping. When the 0.0.0.0/0 SPD entry technique - is used, then the mapping to a gateway is determined by the reverse - DNS records. - - The need to do a DNS lookup and wait for a reply will typically - introduce a new state and a new event source (DNS replies) to IKE. - Although a synchronous DNS request can be implemented for proof of - concept, experience is that it can cause very high latencies when a - queue of queries must all timeout in series. - - Use of an asynchronous DNS lookup will also permit overlap of DNS - lookups with some of the protocol steps. - -4.3 Self identification - - SG-A will have to establish its identity. Use an IPv4 ID in phase 1. - - There are many situations where the administrator of SG-A may not be - able to control the reverse DNS records for SG-A's public IP address. - Typical situations include dialup connections and most residential- - type broadband Internet access (ADSL, cable-modem) connections. In - these situations, a fully qualified domain name that is under the - control of SG-A's administrator may be used when acting as an - initiator only. The FQDN ID should be used in phase 1. See Section - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 21] - -Internet-Draft opportunistic May 2003 - - - 5.3 for more details and restrictions. - -4.4 Public key retrieval process - - Upon receipt of a phase 1 SA proposal with either an IPv4 (IPv6) ID - or an FQDN ID, an IKE daemon needs to examine local caches and - configuration files to determine if this is part of a configured - tunnel. If no configured tunnels are found, then the implementation - should attempt to retrieve a KEY record from the reverse DNS in the - case of an IPv4/IPv6 ID, or from the forward DNS in the case of FQDN - ID. - - It is reasonable that if other non-local sources of policy are used - (COPS, LDAP), they be consulted concurrently but some clear ordering - of policy be provided. Note that due to variances in latency, - implementations must wait for positive or negative replies from all - sources of policy before making any decisions. - -4.5 Interactions with DNSSEC - - The implementation described (1.98) neither uses DNSSEC directly to - explicitly verify the authenticity of zone information, nor uses the - NXT records to provide authentication of the absence of a TXT or KEY - record. Rather, this implementation uses a trusted path to a DNSSEC - capable caching resolver. - - To distinguish between an authenticated and an unauthenticated DNS - resource record, a stub resolver capable of returning DNSSEC - information MUST be used. - -4.6 Required proposal types - -4.6.1 Phase 1 parameters - - Main mode MUST be used. - - The initiator MUST offer at least one proposal using some combination - of: 3DES, HMAC-MD5 or HMAC-SHA1, DH group 2 or 5. Group 5 SHOULD be - proposed first. [11] - - The initiator MAY offer additional proposals, but the cipher MUST not - be weaker than 3DES. The initiator SHOULD limit the number of - proposals such that the IKE datagrams do not need to be fragmented. - - The responder MUST accept one of the proposals. If any configuration - of the responder is required then the responder is not acting in an - opportunistic way. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 22] - -Internet-Draft opportunistic May 2003 - - - SG-A SHOULD use an ID_IPV4_ADDR (ID_IPV6_ADDR for IPv6) of the - external interface of SG-A for phase 1. (There is an exception, see - Section 5.3.) The authentication method MUST be RSA public key - signatures. The RSA key for SG-A SHOULD be placed into a DNS KEY - record in the reverse space of SG-A (i.e. using in-addr.arpa). - -4.6.2 Phase 2 parameters - - SG-A MUST propose a tunnel between Alice and Bob, using 3DES-CBC - mode, MD5 or SHA1 authentication. Perfect Forward Secrecy MUST be - specified. - - Tunnel mode MUST be used. - - Identities MUST be ID_IPV4_ADDR_SUBNET with the mask being /32. - - Authorization for SG-A to act on Alice's behalf is determined by - looking for a TXT record in the reverse-map at Alice's address. - - Compression SHOULD NOT be mandatory. It may be offered as an option. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 23] - -Internet-Draft opportunistic May 2003 - - -5. DNS issues - -5.1 Use of KEY record - - In order to establish their own identities, SG-A and SG-B SHOULD - publish their public keys in their reverse DNS via DNSSEC's KEY - record. See section 3 of RFC 2535 [16]. - - For example: - - KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8 - - 0x4200: The flag bits, indicating that this key is prohibited for - confidentiality use (it authenticates the peer only, a separate - Diffie-Hellman exchange is used for confidentiality), and that - this key is associated with the non-zone entity whose name is the - RR owner name. No other flags are set. - - 4: This indicates that this key is for use by IPsec. - - 1: An RSA key is present. - - AQNJjkKlIk9...nYyUkKK8: The public key of the host as described in - [17]. - - Use of several KEY records allows for key rollover. The SIG Payload - in IKE phase 1 SHOULD be accepted if the public key given by any KEY - RR validates it. - -5.2 Use of TXT delegation record - - Alice publishes a TXT record to provide authorization for SG-A to act - on Alice's behalf. Bob publishes a TXT record to provide - authorization for SG-B to act on Bob's behalf. These records are - located in the reverse DNS (in-addr.arpa) for their respective IP - addresses. The reverse DNS SHOULD be secured by DNSSEC, when it is - deployed. DNSSEC is required to defend against active attacks. - - If Alice's address is P.Q.R.S, then she can authorize another node to - act on her behalf by publishing records at: - - S.R.Q.P.in-addr.arpa - - The contents of the resource record are expected to be a string that - uses the following syntax, as suggested in [15]. (Note that the - reply to query may include other TXT resource records used by other - applications.) - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 24] - -Internet-Draft opportunistic May 2003 - - - --------------------------------------------------------------------- - - - X-IPsec-Server(P)=A.B.C.D KEY - - Figure 2: Format of reverse delegation record - - --------------------------------------------------------------------- - - P: Specifies a precedence for this record. This is similar to MX - record preferences. Lower numbers have stronger preference. - - A.B.C.D: Specifies the IP address of the Security Gateway for this - client machine. - - KEY: Is the encoded RSA Public key of the Security Gateway. The key - is provided here to avoid a second DNS lookup. If this field is - absent, then a KEY resource record should be looked up in the - reverse-map of A.B.C.D. The key is transmitted in base64 format. - - The pieces of the record are separated by any whitespace (space, tab, - newline, carriage return). An ASCII space SHOULD be used. - - In the case where Alice is located at a public address behind a - security gateway that has no fixed address (or no control over its - reverse-map), then Alice may delegate to a public key by domain name. - - --------------------------------------------------------------------- - - - X-IPsec-Server(P)=@FQDN KEY - - Figure 3: Format of reverse delegation record (FQDN version) - - --------------------------------------------------------------------- - - P: Is as above. - - FQDN: Specifies the FQDN that the Security Gateway will identify - itself with. - - KEY: Is the encoded RSA Public key of the Security Gateway. - - If there is more than one such TXT record with strongest (lowest - numbered) precedence, one Security Gateway is picked arbitrarily from - those specified in the strongest-preference records. - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 25] - -Internet-Draft opportunistic May 2003 - - -5.2.1 Long TXT records - - When packed into transport format, TXT records which are longer than - 255 characters are divided into smaller . (See - [13] section 3.3 and 3.3.14.) These MUST be reassembled into a single - string for processing. Whitespace characters in the base64 encoding - are to be ignored. - -5.2.2 Choice of TXT record - - It has been suggested to use the KEY, OPT, CERT, or KX records - instead of a TXT record. None is satisfactory. - - The KEY RR has a protocol field which could be used to indicate a new - protocol, and an algorithm field which could be used to indicate - different contents in the key data. However, the KEY record is - clearly not intended for storing what are really authorizations, it - is just for identities. Other uses have been discouraged. - - OPT resource records, as defined in [14] are not intended to be used - for storage of information. They are not to be loaded, cached or - forwarded. They are, therefore, inappropriate for use here. - - CERT records [18] can encode almost any set of information. A custom - type code could be used permitting any suitable encoding to be - stored, not just X.509. According to the RFC, the certificate RRs - are to be signed internally which may add undesirable and unnecessary - bulk. Larger DNS records may require TCP instead of UDP transfers. - - At the time of protocol design, the CERT RR was not widely deployed - and could not be counted upon. Use of CERT records will be - investigated, and may be proposed in a future revision of this - document. - - KX records are ideally suited for use instead of TXT records, but had - not been deployed at the time of implementation. - -5.3 Use of FQDN IDs - - Unfortunately, not every administrator has control over the contents - of the reverse-map. Where the initiator (SG-A) has no suitable - reverse-map, the authorization record present in the reverse-map of - Alice may refer to a FQDN instead of an IP address. - - In this case, the client's TXT record gives the fully qualified - domain name (FQDN) in place of its security gateway's IP address. - The initiator should use the ID_FQDN ID-payload in phase 1. A - forward lookup for a KEY record on the FQDN must yield the - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 26] - -Internet-Draft opportunistic May 2003 - - - initiator's public key. - - This method can also be used when the external address of SG-A is - dynamic. - - If SG-A is acting on behalf of Alice, then Alice must still delegate - authority for SG-A to do so in her reverse-map. When Alice and SG-A - are one and the same (i.e. Alice is acting as an end-node) then - there is no need for this when initiating only. - - However, Alice must still delegate to herself if she wishes others - to initiate OE to her. See Figure 3. - -5.4 Key roll-over - - Good cryptographic hygiene says that one should replace public/ - private key pairs periodically. Some administrators may wish to do - this as often as daily. Typical DNS propagation delays are - determined by the SOA Resource Record MINIMUM parameter, which - controls how long DNS replies may be cached. For reasonable - operation of DNS servers, administrators usually want this value to - be at least several hours, sometimes as a long as a day. This - presents a problem - a new key MUST not be used prior to it - propagating through DNS. - - This problem is dealt with by having the Security Gateway generate a - new public/private key pair at least MINIMUM seconds in advance of - using it. It then adds this key to the DNS (both as a second KEY - record and in additional TXT delegation records) at key generation - time. Note: only one key is allowed in each TXT record. - - When authenticating, all gateways MUST have available all public keys - that are found in DNS for this entity. This permits the - authenticating end to check both the key for "today" and the key for - "tomorrow". Note that it is the end which is creating the signature - (possesses the private key) that determines which key is to be used. - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 27] - -Internet-Draft opportunistic May 2003 - - -6. Network address translation interaction - - There are no fundamentally new issues for implementing opportunistic - encryption in the presence of network address translation. Rather - there are only the regular IPsec issues with NAT traversal. - - There are several situations to consider for NAT. - -6.1 Co-located NAT/NAPT - - If SG-A is also performing network address translation on behalf of - Alice, then the packet should be translated prior to being subjected - to opportunistic encryption. This is in contrast to typically - configured tunnels which often exist to bridge islands of private - network address space. SG-A will use the translated source address - for phase 2, and so SG-B will look up that address to confirm SG-A's - authorization. - - In the case of NAT (1:1), the address space into which the - translation is done MUST be globally unique, and control over the - reverse-map is assumed. Placing of TXT records is possible. - - In the case of NAPT (m:1), the address will be SG-A. The ability to - get KEY and TXT records in place will again depend upon whether or - not there is administrative control over the reverse-map. This is - identical to situations involving a single host acting on behalf of - itself. FQDN style can be used to get around a lack of a reverse-map - for initiators only. - -6.2 SG-A behind NAT/NAPT - - If there is a NAT or NAPT between SG-A and SG-B, then normal IPsec - NAT traversal rules apply. In addition to the transport problem - which may be solved by other mechanisms, there is the issue of what - phase 1 and phase 2 IDs to use. While FQDN could be used during - phase 1 for SG-A, there is no appropriate ID for phase 2 that permits - SG-B to determine that SG-A is in fact authorized to speak for Alice. - -6.3 Bob is behind a NAT/NAPT - - If Bob is behind a NAT (perhaps SG-B), then there is, in fact, no way - for Alice to address a packet to Bob. Not only is opportunistic - encryption impossible, but it is also impossible for Alice to - initiate any communication to Bob. It may be possible for Bob to - initiate in such a situation. This creates an asymmetry, but this is - common for NAPT. - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 28] - -Internet-Draft opportunistic May 2003 - - -7. Host implementations - - When Alice and SG-A are components of the same system, they are - considered to be a host implementation. The packet sequence scenario - remains unchanged. - - Components marked Alice are the upper layers (TCP, UDP, the - application), and SG-A is the IP layer. - - Note that tunnel mode is still required. - - As Alice and SG-A are acting on behalf of themselves, no TXT based - delegation record is necessary for Alice to initiate. She can rely - on FQDN in a forward map. This is particularly attractive to mobile - nodes such as notebook computers at conferences. To respond, Alice/ - SG-A will still need an entry in Alice's reverse-map. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 29] - -Internet-Draft opportunistic May 2003 - - -8. Multi-homing - - If there are multiple paths between Alice and Bob (as illustrated in - the diagram with SG-D), then additional DNS records are required to - establish authorization. - - In Figure 1, Alice has two ways to exit her network: SG-A and SG-D. - Previously SG-D has been ignored. Postulate that there are routers - between Alice and her set of security gateways (denoted by the + - signs and the marking of an autonomous system number for Alice's - network). Datagrams may, therefore, travel to either SG-A or SG-D en - route to Bob. - - As long as all network connections are in good order, it does not - matter how datagrams exit Alice's network. When they reach either - security gateway, the security gateway will find the TXT delegation - record in Bob's reverse-map, and establish an SA with SG-B. - - SG-B has no problem establishing that either of SG-A or SG-D may - speak for Alice, because Alice has published two equally weighted TXT - delegation records: - - --------------------------------------------------------------------- - - - X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q== - X-IPsec-Server(10)=192.1.1.6 AAJN...j8r9== - - Figure 4: Multiple gateway delegation example for Alice - - --------------------------------------------------------------------- - - Alice's routers can now do any kind of load sharing needed. Both SG- - A and SG-D send datagrams addressed to Bob through their tunnel to - SG-B. - - Alice's use of non-equal weight delegation records to show preference - of one gateway over another, has relevance only when SG-B is - initiating to Alice. - - If the precedences are the same, then SG-B has a more difficult time. - It must decide which of the two tunnels to use. SG-B has no - information about which link is less loaded, nor which security - gateway has more cryptographic resources available. SG-B, in fact, - has no knowledge of whether both gateways are even reachable. - - The Public Internet's default-free zone may well know a good route to - Alice, but the datagrams that SG-B creates must be addressed to - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 30] - -Internet-Draft opportunistic May 2003 - - - either SG-A or SG-D; they can not be addressed to Alice directly. - - SG-B may make a number of choices: - - 1. It can ignore the problem and round robin among the tunnels. - This causes losses during times when one or the other security - gateway is unreachable. If this worries Alice, she can change - the weights in her TXT delegation records. - - 2. It can send to the gateway from which it most recently received - datagrams. This assumes that routing and reachability are - symmetrical. - - 3. It can listen to BGP information from the Internet to decide - which system is currently up. This is clearly much more - complicated, but if SG-B is already participating in the BGP - peering system to announce Bob, the results data may already be - available to it. - - 4. It can refuse to negotiate the second tunnel. (It is unclear - whether or not this is even an option.) - - 5. It can silently replace the outgoing portion of the first tunnel - with the second one while still retaining the incoming portions - of both. SG-B can, thus, accept datagrams from either SG-A or - SG-D, but send only to the gateway that most recently re-keyed - with it. - - Local policy determines which choice SG-B makes. Note that even if - SG-B has perfect knowledge about the reachability of SG-A and SG-D, - Alice may not be reachable from either of these security gateways - because of internal reachability issues. - - FreeS/WAN implements option 5. Implementing a different option is - being considered. The multi-homing aspects of OE are not well - developed and may be the subject of a future document. - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 31] - -Internet-Draft opportunistic May 2003 - - -9. Failure modes - -9.1 DNS failures - - If a DNS server fails to respond, local policy decides whether or not - to permit communication in the clear as embodied in the connection - classes in Section 3.2. It is easy to mount a denial of service - attack on the DNS server responsible for a particular network's - reverse-map. Such an attack may cause all communication with that - network to go in the clear if the policy is permissive, or fail - completely if the policy is paranoid. Please note that this is an - active attack. - - There are still many networks that do not have properly configured - reverse-maps. Further, if the policy is not to communicate, the - above denial of service attack isolates the target network. - Therefore, the decision of whether or not to permit communication in - the clear MUST be a matter of local policy. - -9.2 DNS configured, IKE failures - - DNS records claim that opportunistic encryption should occur, but the - target gateway either does not respond on port 500, or refuses the - proposal. This may be because of a crash or reboot, a faulty - configuration, or a firewall filtering port 500. - - The receipt of ICMP port, host or network unreachable messages - indicates a potential problem, but MUST NOT cause communication to - fail immediately. ICMP messages are easily forged by attackers. If - such a forgery caused immediate failure, then an active attacker - could easily prevent any encryption from ever occurring, possibly - preventing all communication. - - In these situations a clear log should be produced and local policy - should dictate if communication is then permitted in the clear. - -9.3 System reboots - - Tunnels sometimes go down because the remote end crashes, - disconnects, or has a network link break. In general there is no - notification of this. Even in the event of a crash and successful - reboot, other SGs don't hear about it unless the rebooted SG has - specific reason to talk to them immediately. Over-quick response to - temporary network outages is undesirable. Note that a tunnel can be - torn down and then re-established without any effect visible to the - user except a pause in traffic. On the other hand, if one end - reboots, the other end can't get datagrams to it at all (except via - IKE) until the situation is noticed. So a bias toward quick response - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 32] - -Internet-Draft opportunistic May 2003 - - - is appropriate even at the cost of occasional false alarms. - - A mechanism for recovery after reboot is a topic of current research - and is not specified in this document. - - A deliberate shutdown should include an attempt, using deletes, to - notify all other SGs currently connected by phase 1 SAs that - communication is about to fail. Again, a remote SG will assume this - is a teardown. Attempts by the remote SGs to negotiate new tunnels - as replacements should be ignored. When possible, SGs should attempt - to preserve information about currently-connected SGs in non-volatile - storage, so that after a crash, an Initial-Contact can be sent to - previous partners to indicate loss of all previously established - connections. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 33] - -Internet-Draft opportunistic May 2003 - - -10. Unresolved issues - -10.1 Control of reverse DNS - - The method of obtaining information by reverse DNS lookup causes - problems for people who cannot control their reverse DNS bindings. - This is an unresolved problem in this version, and is out of scope. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 34] - -Internet-Draft opportunistic May 2003 - - -11. Examples - -11.1 Clear-text usage (permit policy) - - Two example scenarios follow. In the first example GW-A (Gateway A) - and GW-B (Gateway B) have always-clear-text policies, and in the - second example they have an OE policy. - - --------------------------------------------------------------------- - - - Alice SG-A DNS SG-B Bob - (1) - ------(2)--------------> - <-----(3)--------------- - (4)----(5)-----> - ----------(6)------> - ------(7)-----> - <------(8)------ - <----------(9)------ - <----(10)----- - (11)-----------> - ----------(12)-----> - --------------> - <--------------- - <------------------- - <------------- - - Figure 5: Timing of regular transaction - - --------------------------------------------------------------------- - - Alice wants to communicate with Bob. Perhaps she wants to retrieve a - web page from Bob's web server. In the absence of opportunistic - encryptors, the following events occur: - - (1) Human or application 'clicks' with a name. - - (2) Application looks up name in DNS to get IP address. - - (3) Resolver returns A record to application. - - (4) Application starts a TCP session or UDP session and OS sends - datagram. - - (5) Datagram is seen at first gateway from Alice (SG-A). (SG-A makes - a transition through Empty connection to always-clear connection - and instantiates a pass-through policy at the forwarding plane.) - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 35] - -Internet-Draft opportunistic May 2003 - - - (6) Datagram is seen at last gateway before Bob (SG-B). - - (7) First datagram from Alice is seen by Bob. - - (8) First return datagram is sent by Bob. - - (9) Datagram is seen at Bob's gateway. (SG-B makes a transition - through Empty connection to always-clear connection and - instantiates a pass-through policy at the forwarding plane.) - - (10) Datagram is seen at Alice's gateway. - - (11) OS hands datagram to application. Alice sends another datagram. - - (12) A second datagram traverses the Internet. - - -11.2 Opportunistic encryption - - In the presence of properly configured opportunistic encryptors, the - event list is extended. - - --------------------------------------------------------------------- - - - Alice SG-A DNS SG-B Bob - (1) - ------(2)--------------> - <-----(3)--------------- - (4)----(5)----->+ - ----(5B)-> - <---(5C)-- - ~~~~~~~~~~~~~(5D)~~~> - <~~~~~~~~~~~~(5E1)~~~ - ~~~~~~~~~~~~~(5E2)~~> - <~~~~~~~~~~~~(5E3)~~~ - #############(5E4)##> - <############(5E5)### - <----(5F1)-- - -----(5F2)-> - #############(5G1)##> - <----(5H1)-- - -----(5H2)-> - <############(5G2)### - #############(5G3)##> - ============(6)====> - ------(7)-----> - <------(8)------ - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 36] - -Internet-Draft opportunistic May 2003 - - - <==========(9)====== - <-----(10)---- - (11)-----------> - ==========(12)=====> - --------------> - <--------------- - <=================== - <------------- - - Figure 6: Timing of opportunistic encryption transaction - - --------------------------------------------------------------------- - - (1) Human or application clicks with a name. - - (2) Application initiates DNS mapping. - - (3) Resolver returns A record to application. - - (4) Application starts a TCP session or UDP. - - (5) SG-A (host or SG) sees datagram to target, and buffers it. - - (5B) SG-A asks DNS for TXT record. - - (5C) DNS returns TXT record(s). - - (5D) Initial IKE Main Mode Packet goes out. - - (5E) IKE ISAKMP phase 1 succeeds. - - (5F) SG-B asks DNS for TXT record to prove SG-A is an agent for - Alice. - - (5G) IKE phase 2 negotiation. - - (5H) DNS lookup by responder (SG-B). - - (6) Buffered datagram is sent by SG-A. - - (7) Datagram is received by SG-B, decrypted, and sent to Bob. - - (8) Bob replies, and datagram is seen by SG-B. - - (9) SG-B already has tunnel up with SG-A, and uses it. - - (10) SG-A decrypts datagram and gives it to Alice. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 37] - -Internet-Draft opportunistic May 2003 - - - (11) Alice receives datagram. Sends new packet to Bob. - - (12) SG-A gets second datagram, sees that tunnel is up, and uses it. - - For the purposes of this section, we will describe only the changes - that occur between Figure 5 and Figure 6. This corresponds to time - points 5, 6, 7, 9 and 10 on the list above. - -11.2.1 (5) IPsec datagram interception - - At point (5), SG-A intercepts the datagram because this source/ - destination pair lacks a policy (the non-existent policy state). SG- - A creates a hold policy, and buffers the datagram. SG-A requests - keys from the keying daemon. - -11.2.2 (5B) DNS lookup for TXT record - - SG-A's IKE daemon, having looked up the source/destination pair in - the connection class list, creates a new Potential OE connection - instance. SG-A starts DNS queries. - -11.2.3 (5C) DNS returns TXT record(s) - - DNS returns properly formed TXT delegation records, and SG-A's IKE - daemon causes this instance to make a transition from Potential OE - connection to Pending OE connection. - - Using the example above, the returned record might contain: - - --------------------------------------------------------------------- - - - X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q== - - Figure 7: Example of reverse delegation record for Bob - - --------------------------------------------------------------------- - - with SG-B's IP address and public key listed. - -11.2.4 (5D) Initial IKE main mode packet goes out - - Upon entering Pending OE connection, SG-A sends the initial ISAKMP - message with proposals. See Section 4.6.1. - -11.2.5 (5E1) Message 2 of phase 1 exchange - - SG-B receives the message. A new connection instance is created in - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 38] - -Internet-Draft opportunistic May 2003 - - - the unauthenticated OE peer state. - -11.2.6 (5E2) Message 3 of phase 1 exchange - - SG-A sends a Diffie-Hellman exponent. This is an internal state of - the keying daemon. - -11.2.7 (5E3) Message 4 of phase 1 exchange - - SG-B responds with a Diffie-Hellman exponent. This is an internal - state of the keying protocol. - -11.2.8 (5E4) Message 5 of phase 1 exchange - - SG-A uses the phase 1 SA to send its identity under encryption. The - choice of identity is discussed in Section 4.6.1. This is an - internal state of the keying protocol. - -11.2.9 (5F1) Responder lookup of initiator key - - SG-B asks DNS for the public key of the initiator. DNS looks for a - KEY record by IP address in the reverse-map. That is, a KEY resource - record is queried for 4.1.1.192.in-addr.arpa (recall that SG-A's - external address is 192.1.1.4). SG-B uses the resulting public key - to authenticate the initiator. See Section 5.1 for further details. - -11.2.10 (5F2) DNS replies with public key of initiator - - Upon successfully authenticating the peer, the connection instance - makes a transition to authenticated OE peer on SG-B. - - The format of the TXT record returned is described in Section 5.2. - -11.2.11 (5E5) Responder replies with ID and authentication - - SG-B sends its ID along with authentication material. This is an - internal state for the keying protocol. - -11.2.12 (5G) IKE phase 2 - -11.2.12.1 (5G1) Initiator proposes tunnel - - Having established mutually agreeable authentications (via KEY) and - authorizations (via TXT), SG-A proposes to create an IPsec tunnel for - datagrams transiting from Alice to Bob. This tunnel is established - only for the Alice/Bob combination, not for any subnets that may be - behind SG-A and SG-B. - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 39] - -Internet-Draft opportunistic May 2003 - - -11.2.12.2 (5H1) Responder determines initiator's authority - - While the identity of SG-A has been established, its authority to - speak for Alice has not yet been confirmed. SG-B does a reverse - lookup on Alice's address for a TXT record. - - Upon receiving this specific proposal, SG-B's connection instance - makes a transition into the potential OE connection state. SG-B may - already have an instance, and the check is made as described above. - -11.2.12.3 (5H2) DNS replies with TXT record(s) - - The returned key and IP address should match that of SG-A. - -11.2.12.4 (5G2) Responder agrees to proposal - - Should additional communication occur between, for instance, Dave and - Bob using SG-A and SG-B, a new tunnel (phase 2 SA) would be - established. The phase 1 SA may be reusable. - - SG-A, having successfully keyed the tunnel, now makes a transition - from Pending OE connection to Keyed OE connection. - - The responder MUST setup the inbound IPsec SAs before sending its - reply. - -11.2.12.5 (5G3) Final acknowledgment from initiator - - The initiator agrees with the responder's choice and sets up the - tunnel. The initiator sets up the inbound and outbound IPsec SAs. - - The proper authorization returned with keys prompts SG-B to make a - transition to the keyed OE connection state. - - Upon receipt of this message, the responder may now setup the - outbound IPsec SAs. - -11.2.13 (6) IPsec succeeds, and sets up tunnel for communication between - Alice and Bob - - SG-A sends the datagram saved at step (5) through the newly created - tunnel to SG-B, where it gets decrypted and forwarded. Bob receives - it at (7) and replies at (8). - -11.2.14 (9) SG-B already has tunnel up with G1 and uses it - - At (9), SG-B has already established an SPD entry mapping Bob->Alice - via a tunnel, so this tunnel is simply applied. The datagram is - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 40] - -Internet-Draft opportunistic May 2003 - - - encrypted to SG-A, decrypted by SG-A and passed to Alice at (10). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 41] - -Internet-Draft opportunistic May 2003 - - -12. Security considerations - -12.1 Configured vs opportunistic tunnels - - Configured tunnels are those which are setup using bilateral - mechanisms: exchanging public keys (raw RSA, DSA, PKIX), pre-shared - secrets, or by referencing keys that are in known places - (distinguished name from LDAP, DNS). These keys are then used to - configure a specific tunnel. - - A pre-configured tunnel may be on all the time, or may be keyed only - when needed. The end points of the tunnel are not necessarily - static: many mobile applications (road warrior) are considered to be - configured tunnels. - - The primary characteristic is that configured tunnels are assigned - specific security properties. They may be trusted in different ways - relating to exceptions to firewall rules, exceptions to NAT - processing, and to bandwidth or other quality of service - restrictions. - - Opportunistic tunnels are not inherently trusted in any strong way. - They are created without prior arrangement. As the two parties are - strangers, there MUST be no confusion of datagrams that arrive from - opportunistic peers and those that arrive from configured tunnels. A - security gateway MUST take care that an opportunistic peer can not - impersonate a configured peer. - - Ingress filtering MUST be used to make sure that only datagrams - authorized by negotiation (and the concomitant authentication and - authorization) are accepted from a tunnel. This is to prevent one - peer from impersonating another. - - An implementation suggestion is to treat opportunistic tunnel - datagrams as if they arrive on a logical interface distinct from - other configured tunnels. As the number of opportunistic tunnels - that may be created automatically on a system is potentially very - high, careful attention to scaling should be taken into account. - - As with any IKE negotiation, opportunistic encryption cannot be - secure without authentication. Opportunistic encryption relies on - DNS for its authentication information and, therefore, cannot be - fully secure without a secure DNS. Without secure DNS, opportunistic - encryption can protect against passive eavesdropping but not against - active man-in-the-middle attacks. - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 42] - -Internet-Draft opportunistic May 2003 - - -12.2 Firewalls versus Opportunistic Tunnels - - Typical usage of per datagram access control lists is to implement - various kinds of security gateways. These are typically called - "firewalls". - - Typical usage of a virtual private network (VPN) within a firewall is - to bypass all or part of the access controls between two networks. - Additional trust (as outlined in the previous section) is given to - datagrams that arrive in the VPN. - - Datagrams that arrive via opportunistically configured tunnels MUST - not be trusted. Any security policy that would apply to a datagram - arriving in the clear SHOULD also be applied to datagrams arriving - opportunistically. - -12.3 Denial of service - - There are several different forms of denial of service that an - implementor should concern themselves with. Most of these problems - are shared with security gateways that have large numbers of mobile - peers (road warriors). - - The design of ISAKMP/IKE, and its use of cookies, defend against many - kinds of denial of service. Opportunism changes the assumption that - if the phase 1 (ISAKMP) SA is authenticated, that it was worthwhile - creating. Because the gateway will communicate with any machine, it - is possible to form phase 1 SAs with any machine on the Internet. - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 43] - -Internet-Draft opportunistic May 2003 - - -13. IANA Considerations - - There are no known numbers which IANA will need to manage. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 44] - -Internet-Draft opportunistic May 2003 - - -14. Acknowledgments - - Substantive portions of this document are based upon previous work by - Henry Spencer. - - Thanks to Tero Kivinen, Sandy Harris, Wes Hardarker, Robert - Moskowitz, Jakob Schlyter, Bill Sommerfeld, John Gilmore and John - Denker for their comments and constructive criticism. - - Sandra Hoffman and Bill Dickie did the detailed proof reading and - editing. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 45] - -Internet-Draft opportunistic May 2003 - - -Normative references - - [1] Redelmeier, D. and H. Spencer, "Opportunistic Encryption", - paper http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/ - opportunism.spec, May 2001. - - [2] Defense Advanced Research Projects Agency (DARPA), Information - Processing Techniques Office and University of Southern - California (USC)/Information Sciences Institute, "Internet - Protocol", STD 5, RFC 791, September 1981. - - [3] Braden, R. and J. Postel, "Requirements for Internet gateways", - RFC 1009, June 1987. - - [4] IAB, IESG, Carpenter, B. and F. Baker, "IAB and IESG Statement - on Cryptographic Technology and the Internet", RFC 1984, August - 1996. - - [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - - [6] McDonald, D., Metz, C. and B. Phan, "PF_KEY Key Management API, - Version 2", RFC 2367, July 1998. - - [7] Kent, S. and R. Atkinson, "Security Architecture for the - Internet Protocol", RFC 2401, November 1998. - - [8] Piper, D., "The Internet IP Security Domain of Interpretation - for ISAKMP", RFC 2407, November 1998. - - [9] Maughan, D., Schneider, M. and M. Schertler, "Internet Security - Association and Key Management Protocol (ISAKMP)", RFC 2408, - November 1998. - - [10] Harkins, D. and D. Carrel, "The Internet Key Exchange (IKE)", - RFC 2409, November 1998. - - [11] Kivinen, T. and M. Kojo, "More MODP Diffie-Hellman groups for - IKE", RFC 3526, March 2003. - - [12] Mockapetris, P., "Domain names - concepts and facilities", STD - 13, RFC 1034, November 1987. - - [13] Mockapetris, P., "Domain names - implementation and - specification", STD 13, RFC 1035, November 1987. - - [14] Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC 2671, - August 1999. - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 46] - -Internet-Draft opportunistic May 2003 - - - [15] Rosenbaum, R., "Using the Domain Name System To Store Arbitrary - String Attributes", RFC 1464, May 1993. - - [16] Eastlake, D., "Domain Name System Security Extensions", RFC - 2535, March 1999. - - [17] Eastlake, D., "RSA/SHA-1 SIGs and RSA KEYs in the Domain Name - System (DNS)", RFC 3110, May 2001. - - [18] Eastlake, D. and O. Gudmundsson, "Storing Certificates in the - Domain Name System (DNS)", RFC 2538, March 1999. - - [19] Durham, D., Boyle, J., Cohen, R., Herzog, S., Rajan, R. and A. - Sastry, "The COPS (Common Open Policy Service) Protocol", RFC - 2748, January 2000. - - [20] Srisuresh, P. and M. Holdrege, "IP Network Address Translator - (NAT) Terminology and Considerations", RFC 2663, August 1999. - - -Authors' Addresses - - Michael C. Richardson - Sandelman Software Works - 470 Dawson Avenue - Ottawa, ON K1Z 5V7 - CA - - EMail: mcr@sandelman.ottawa.on.ca - URI: http://www.sandelman.ottawa.on.ca/ - - - D. Hugh Redelmeier - Mimosa - Toronto, ON - CA - - EMail: hugh@mimosa.com - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 47] - -Internet-Draft opportunistic May 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Richardson & Redelmeier Expires November 19, 2003 [Page 48] - diff --git a/doc/draft-richardson-ipsec-rr.txt b/doc/draft-richardson-ipsec-rr.txt deleted file mode 100644 index 7c229b8e1..000000000 --- a/doc/draft-richardson-ipsec-rr.txt +++ /dev/null @@ -1,840 +0,0 @@ - - -IPSECKEY WG M. Richardson -Internet-Draft SSW -Expires: March 4, 2004 September 4, 2003 - - - A method for storing IPsec keying material in DNS. - draft-ietf-ipseckey-rr-07.txt - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at http:// - www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on March 4, 2004. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This document describes a new resource record for DNS. This record - may be used to store public keys for use in IPsec systems. - - This record replaces the functionality of the sub-type #1 of the KEY - Resource Record, which has been obsoleted by RFC3445. - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 1] - -Internet-Draft ipsecrr September 2003 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.2 Usage Criteria . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Storage formats . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.1 IPSECKEY RDATA format . . . . . . . . . . . . . . . . . . . . 4 - 2.2 RDATA format - precedence . . . . . . . . . . . . . . . . . . 4 - 2.3 RDATA format - algorithm type . . . . . . . . . . . . . . . . 4 - 2.4 RDATA format - gateway type . . . . . . . . . . . . . . . . . 4 - 2.5 RDATA format - gateway . . . . . . . . . . . . . . . . . . . . 5 - 2.6 RDATA format - public keys . . . . . . . . . . . . . . . . . . 5 - 3. Presentation formats . . . . . . . . . . . . . . . . . . . . . 7 - 3.1 Representation of IPSECKEY RRs . . . . . . . . . . . . . . . . 7 - 3.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 - 4.1 Active attacks against unsecured IPSECKEY resource records . . 9 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 - 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 - Normative references . . . . . . . . . . . . . . . . . . . . . 13 - Non-normative references . . . . . . . . . . . . . . . . . . . 14 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . 14 - Full Copyright Statement . . . . . . . . . . . . . . . . . . . 15 - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 2] - -Internet-Draft ipsecrr September 2003 - - -1. Introduction - - The type number for the IPSECKEY RR is TBD. - -1.1 Overview - - The IPSECKEY resource record (RR) is used to publish a public key - that is to be associated with a Domain Name System (DNS) name for use - with the IPsec protocol suite. This can be the public key of a - host, network, or application (in the case of per-port keying). - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC2119 [8]. - -1.2 Usage Criteria - - An IPSECKEY resource record SHOULD be used in combination with DNSSEC - unless some other means of authenticating the IPSECKEY resource - record is available. - - It is expected that there will often be multiple IPSECKEY resource - records at the same name. This will be due to the presence of - multiple gateways and the need to rollover keys. - - This resource record is class independent. - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 3] - -Internet-Draft ipsecrr September 2003 - - -2. Storage formats - -2.1 IPSECKEY RDATA format - - The RDATA for an IPSECKEY RR consists of a precedence value, a public - key, algorithm type, and an optional gateway address. - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | precedence | gateway type | algorithm | gateway | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------+ + - ~ gateway ~ - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | / - / public key / - / / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-| - - -2.2 RDATA format - precedence - - This is an 8-bit precedence for this record. This is interpreted in - the same way as the PREFERENCE field described in section 3.3.9 of - RFC1035 [2]. - - Gateways listed in IPSECKEY records with lower precedence are to be - attempted first. Where there is a tie in precedence, the order - should be non-deterministic. - -2.3 RDATA format - algorithm type - - The algorithm type field identifies the public key's cryptographic - algorithm and determines the format of the public key field. - - A value of 0 indicates that no key is present. - - The following values are defined: - - 1 A DSA key is present, in the format defined in RFC2536 [11] - - 2 A RSA key is present, in the format defined in RFC3110 [12] - - -2.4 RDATA format - gateway type - - The gateway type field indicates the format of the information that - is stored in the gateway field. - - - -Richardson Expires March 4, 2004 [Page 4] - -Internet-Draft ipsecrr September 2003 - - - The following values are defined: - - 0 No gateway is present - - 1 A 4-byte IPv4 address is present - - 2 A 16-byte IPv6 address is present - - 3 A wire-encoded domain name is present. The wire-encoded format is - self-describing, so the length is implicit. The domain name MUST - NOT be compressed. - - -2.5 RDATA format - gateway - - The gateway field indicates a gateway to which an IPsec tunnel may be - created in order to reach the entity named by this resource record. - - There are three formats: - - A 32-bit IPv4 address is present in the gateway field. The data - portion is an IPv4 address as described in section 3.4.1 of RFC1035 - [2]. This is a 32-bit number in network byte order. - - A 128-bit IPv6 address is present in the gateway field. The data - portion is an IPv6 address as described in section 2.2 of RFC1886 - [7]. This is a 128-bit number in network byte order. - - The gateway field is a normal wire-encoded domain name, as described - in section 3.3 of RFC1035 [2]. Compression MUST NOT be used. - -2.6 RDATA format - public keys - - Both of the public key types defined in this document (RSA and DSA) - inherit their public key formats from the corresponding KEY RR - formats. Specifically, the public key field contains the algorithm- - specific portion of the KEY RR RDATA, which is all of the KEY RR DATA - after the first four octets. This is the same portion of the KEY RR - that must be specified by documents that define a DNSSEC algorithm. - Those documents also specify a message digest to be used for - generation of SIG RRs; that specification is not relevant for - IPSECKEY RR. - - Future algorithms, if they are to be used by both DNSSEC (in the KEY - RR) and IPSECKEY, are likely to use the same public key encodings in - both records. Unless otherwise specified, the IPSECKEY public key - field will contain the algorithm-specific portion of the KEY RR RDATA - for the corresponding algorithm. The algorithm must still be - - - -Richardson Expires March 4, 2004 [Page 5] - -Internet-Draft ipsecrr September 2003 - - - designated for use by IPSECKEY, and an IPSECKEY algorithm type number - (which might be different than the DNSSEC algorithm number) must be - assigned to it. - - The DSA key format is defined in RFC2536 [11] - - The RSA key format is defined in RFC3110 [12], with the following - changes: - - The earlier definition of RSA/MD5 in RFC2065 limited the exponent and - modulus to 2552 bits in length. RFC3110 extended that limit to 4096 - bits for RSA/SHA1 keys. The IPSECKEY RR imposes no length limit on - RSA public keys, other than the 65535 octet limit imposed by the two- - octet length encoding. This length extension is applicable only to - IPSECKEY and not to KEY RRs. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 6] - -Internet-Draft ipsecrr September 2003 - - -3. Presentation formats - -3.1 Representation of IPSECKEY RRs - - IPSECKEY RRs may appear in a zone data master file. The precedence, - gateway type and algorithm and gateway fields are REQUIRED. The - base64 encoded public key block is OPTIONAL; if not present, then the - public key field of the resource record MUST be construed as being - zero octets in length. - - The algorithm field is an unsigned integer. No mnemonics are - defined. - - If no gateway is to be indicated, then the gateway type field MUST be - zero, and the gateway field MUST be "." - - The Public Key field is represented as a Base64 encoding of the - Public Key. Whitespace is allowed within the Base64 text. For a - definition of Base64 encoding, see RFC1521 [3] Section 5.2. - - The general presentation for the record as as follows: - - IN IPSECKEY ( precedence gateway-type algorithm - gateway base64-encoded-public-key ) - - -3.2 Examples - - An example of a node 192.0.2.38 that will accept IPsec tunnels on its - own behalf. - - 38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 1 2 - 192.0.2.38 - AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) - - An example of a node, 192.0.2.38 that has published its key only. - - 38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 0 2 - . - AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) - - An example of a node, 192.0.2.38 that has delegated authority to the - node 192.0.2.3. - - 38.2.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 1 2 - 192.0.2.3 - AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) - - - - -Richardson Expires March 4, 2004 [Page 7] - -Internet-Draft ipsecrr September 2003 - - - An example of a node, 192.0.1.38 that has delegated authority to the - node with the identity "mygateway.example.com". - - 38.1.0.192.in-addr.arpa. 7200 IN IPSECKEY ( 10 3 2 - mygateway.example.com. - AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) - - An example of a node, 2001:0DB8:0200:1:210:f3ff:fe03:4d0 that has - delegated authority to the node 2001:0DB8:c000:0200:2::1 - - $ORIGIN 1.0.0.0.0.0.2.8.B.D.0.1.0.0.2.ip6.int. - 0.d.4.0.3.0.e.f.f.f.3.f.0.1.2.0 7200 IN IPSECKEY ( 10 2 2 - 2001:0DB8:0:8002::2000:1 - AQNRU3mG7TVTO2BkR47usntb102uFJtugbo6BSGvgqt4AQ== ) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 8] - -Internet-Draft ipsecrr September 2003 - - -4. Security Considerations - - This entire memo pertains to the provision of public keying material - for use by key management protocols such as ISAKMP/IKE (RFC2407) [9]. - - The IPSECKEY resource record contains information that SHOULD be - communicated to the end client in an integral fashion - i.e. free - from modification. The form of this channel is up to the consumer of - the data - there must be a trust relationship between the end - consumer of this resource record and the server. This relationship - may be end-to-end DNSSEC validation, a TSIG or SIG(0) channel to - another secure source, a secure local channel on the host, or some - combination of the above. - - The keying material provided by the IPSECKEY resource record is not - sensitive to passive attacks. The keying material may be freely - disclosed to any party without any impact on the security properties - of the resulting IPsec session: IPsec and IKE provide for defense - against both active and passive attacks. - - Any user of this resource record MUST carefully document their trust - model, and why the trust model of DNSSEC is appropriate, if that is - the secure channel used. - -4.1 Active attacks against unsecured IPSECKEY resource records - - This section deals with active attacks against the DNS. These - attacks require that DNS requests and responses be intercepted and - changed. DNSSEC is designed to defend against attacks of this kind. - - The first kind of active attack is when the attacker replaces the - keying material with either a key under its control or with garbage. - - If the attacker is not able to mount a subsequent man-in-the-middle - attack on the IKE negotiation after replacing the public key, then - this will result in a denial of service, as the authenticator used by - IKE would fail. - - If the attacker is able to both to mount active attacks against DNS - and is also in a position to perform a man-in-the-middle attack on - IKE and IPsec negotiations, then the attacker will be in a position - to compromise the resulting IPsec channel. Note that an attacker - must be able to perform active DNS attacks on both sides of the IKE - negotiation in order for this to succeed. - - The second kind of active attack is one in which the attacker - replaces the the gateway address to point to a node under the - attacker's control. The attacker can then either replace the public - - - -Richardson Expires March 4, 2004 [Page 9] - -Internet-Draft ipsecrr September 2003 - - - key or remove it, thus providing an IPSECKEY record of its own to - match the gateway address. - - This later form creates a simple man-in-the-middle since the attacker - can then create a second tunnel to the real destination. Note that, - as before, this requires that the attacker also mount an active - attack against the responder. - - Note that the man-in-the-middle can not just forward cleartext - packets to the original destination. While the destination may be - willing to speak in the clear, replying to the original sender, the - sender will have already created a policy expecting ciphertext. - Thus, the attacker will need to intercept traffic from both sides. - In some cases, the attacker may be able to accomplish the full - intercept by use of Network Addresss/Port Translation (NAT/NAPT) - technology. - - Note that the danger here only applies to cases where the gateway - field of the IPSECKEY RR indicates a different entity than the owner - name of the IPSECKEY RR. In cases where the end-to-end integrity of - the IPSECKEY RR is suspect, the end client MUST restrict its use of - the IPSECKEY RR to cases where the RR owner name matches the content - of the gateway field. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 10] - -Internet-Draft ipsecrr September 2003 - - -5. IANA Considerations - - This document updates the IANA Registry for DNS Resource Record Types - by assigning type X to the IPSECKEY record. - - This document creates an IANA registry for the algorithm type field. - - Values 0, 1 and 2 are defined in Section 2.3. Algorithm numbers 3 - through 255 can be assigned by IETF Consensus (see RFC2434 [6]). - - This document creates an IANA registry for the gateway type field. - - Values 0, 1, 2 and 3 are defined in Section 2.4. Algorithm numbers 4 - through 255 can be assigned by Standards Action (see RFC2434 [6]). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 11] - -Internet-Draft ipsecrr September 2003 - - -6. Acknowledgments - - My thanks to Paul Hoffman, Sam Weiler, Jean-Jacques Puig, Rob - Austein, and Olafur Gurmundsson who reviewed this document carefully. - Additional thanks to Olafur Gurmundsson for a reference - implementation. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 12] - -Internet-Draft ipsecrr September 2003 - - -Normative references - - [1] Mockapetris, P., "Domain names - concepts and facilities", STD - 13, RFC 1034, November 1987. - - [2] Mockapetris, P., "Domain names - implementation and - specification", STD 13, RFC 1035, November 1987. - - [3] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet Mail - Extensions) Part One: Mechanisms for Specifying and Describing - the Format of Internet Message Bodies", RFC 1521, September - 1993. - - [4] Bradner, S., "The Internet Standards Process -- Revision 3", BCP - 9, RFC 2026, October 1996. - - [5] Eastlake, D. and C. Kaufman, "Domain Name System Security - Extensions", RFC 2065, January 1997. - - [6] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA - Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 13] - -Internet-Draft ipsecrr September 2003 - - -Non-normative references - - [7] Thomson, S. and C. Huitema, "DNS Extensions to support IP - version 6", RFC 1886, December 1995. - - [8] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - - [9] Piper, D., "The Internet IP Security Domain of Interpretation - for ISAKMP", RFC 2407, November 1998. - - [10] Eastlake, D., "Domain Name System Security Extensions", RFC - 2535, March 1999. - - [11] Eastlake, D., "DSA KEYs and SIGs in the Domain Name System - (DNS)", RFC 2536, March 1999. - - [12] Eastlake, D., "RSA/SHA-1 SIGs and RSA KEYs in the Domain Name - System (DNS)", RFC 3110, May 2001. - - [13] Massey, D. and S. Rose, "Limiting the Scope of the KEY Resource - Record (RR)", RFC 3445, December 2002. - - -Author's Address - - Michael C. Richardson - Sandelman Software Works - 470 Dawson Avenue - Ottawa, ON K1Z 5V7 - CA - - EMail: mcr@sandelman.ottawa.on.ca - URI: http://www.sandelman.ottawa.on.ca/ - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 14] - -Internet-Draft ipsecrr September 2003 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Richardson Expires March 4, 2004 [Page 15] - diff --git a/doc/draft-spencer-ipsec-ike-implementation.nr b/doc/draft-spencer-ipsec-ike-implementation.nr deleted file mode 100644 index 5b5776e22..000000000 --- a/doc/draft-spencer-ipsec-ike-implementation.nr +++ /dev/null @@ -1,1203 +0,0 @@ -.\" date, expiry date, copyright year, and revision -.DA "26 Feb 2002" -.ds e "26 Aug 2002 -.ds c 2002 -.ds r 02 -.\" boilerplate -.pl 10i -.nr PL 10i -.po 0 -.nr PO 0 -.ll 7.2i -.nr LL 7.2i -.lt 7.2i -.nr LT 7.2i -.hy 0 -.nr HY 0 -.ad l -.nr PD 1v -.\" macros for paragraph, section header, reference, TOC -.de P -.br -.LP -.in 3 -.. -.de H -.br -.ne 5 -.LP -.in 0 -.. -.de R -.IP " [\\$1]" 14 -.. -.de T -.ie \\$1=1 \{\ -.nf -.ta \n(LLu-3nR -.\} -.el \{\ -.fi -.\} -.. -.de S -.ie '\\$1'' \\$2 \a \\$3 -.el \\$1. \\$2 \a \\$3 -.. -.\" headers/footers -.ds LH "Internet Draft -.ds CH "IKE Implementation Issues -.ds RH "\*(DY -.ds LF "Spencer & Redelmeier -.ds CF " -.ds RF "[Page %] -.\" and let's get started -.RT -.nf -.tl 'Network Working Group''Henry Spencer' -.tl 'Internet Draft''SP Systems' -.tl 'Expires: \*e''D. Hugh Redelmeier' -.tl '''Mimosa Systems' -.tl '''\*(DY' -.sp -.ce 99 -IKE Implementation Issues - -.ce 0 -.H -Status of this Memo -.P -This document is an Internet-Draft and is in full conformance with -all provisions of Section 10 of RFC2026. -.P -(If approved as an Informational RFC...) -This memo provides information for the Internet community. -This memo does not specify an Internet standard of any kind. -.P -Distribution of this memo is unlimited. -.P -Internet-Drafts are working documents of the Internet Engineering -Task Force (IETF), its areas, and its working groups. -Note that -other groups may also distribute working documents as Internet-Drafts. -.P -Internet-Drafts are draft documents valid for a maximum of six months -and may be updated, replaced, or obsoleted by other documents at any -time. -It is inappropriate to use Internet-Drafts as reference -material or to cite them other than as "work in progress." -.P -The list of current Internet-Drafts can be accessed at -http://www.ietf.org/ietf/1id-abstracts.txt. -.P -The list of Internet-Draft Shadow Directories can be accessed at -http://www.ietf.org/shadow.html. -.P -This Internet-Draft will expire on \*e. -.H -Copyright Notice -.P -Copyright (C) The Internet Society \*c. All Rights Reserved. -.bp -.H -Table of Contents -.P -.T 1 -.S "1" "Introduction" "3" -.S "2" "Lower-level Background and Notes" "4" -.S "2.1" "Packet Handling" "4" -.S "2.2" "Ciphers" "5" -.S "2.3" "Interfaces" "5" -.S "3" "IKE Infrastructural Issues" "5" -.S "3.1" "Continuous Channel" "5" -.S "3.2" "Retransmission" "5" -.S "3.3" "Replay Prevention" "6" -.S "4" "Basic Keying and Rekeying" "7" -.S "4.1" "When to Create SAs" "7" -.S "4.2" "When to Rekey" "8" -.S "4.3" "Choosing an SA" "9" -.S "4.4" "Why to Rekey" "9" -.S "4.5" "Rekeying ISAKMP SAs" "10" -.S "4.6" "Bulk Negotiation" "10" -.S "5" "Deletions, Teardowns, Crashes" "11" -.S "5.1" "Deletions" "11" -.S "5.2" "Teardowns and Shutdowns" "12" -.S "5.3" "Crashes" "13" -.S "5.4" "Network Partitions" "13" -.S "5.5" "Unknown SAs" "14" -.S "6" "Misc. IKE Issues" "16" -.S "6.1" "Groups 1 and 5" "16" -.S "6.2" "To PFS Or Not To PFS" "16" -.S "6.3" "Debugging Tools, Lack Thereof" "16" -.S "6.4" "Terminology, Vagueness Thereof" "17" -.S "6.5" "A Question of Identity" "17" -.S "6.6" "Opportunistic Encryption" "17" -.S "6.7" "Authentication and RSA Keys" "17" -.S "6.8" "Misc. Snags" "18" -.S "7" "Security Considerations" "19" -.S "8" "References" "19" -.S "" "Authors' Addresses" "20" -.S "" "Full Copyright Statement" "21" -.T 0 -.bp -.H -Abstract -.P -The current IPsec specifications for key exchange and connection management, -RFCs 2408 [ISAKMP] and 2409 [IKE], -leave many aspects of connection management unspecified, -most prominently rekeying practices. -Pending clarifications in future revisions of the specifications, -this document sets down some successful experiences, -to minimize the extent to which new implementors have to rely -on unwritten folklore. -.P -The Linux FreeS/WAN implementation of IPsec interoperates -with almost every other IPsec implementation. -This document describes how the FreeS/WAN project has resolved -some of the gaps in the IPsec specifications -(and plans to resolve some others), -and what difficulties have been encountered, -in hopes that this generally-successful experience -might be informative to new implementors. -.P -This is offered as an Informational RFC. -.P -This -\*r revision mainly: -discusses ISAKMP SA expiry during IPsec-SA rekeying (4.5), -revises the discussion of bidirectional Deletes (5.1), -suggests remembering the parameters of successful negotiations -for later use (4.2, 5.3), -notes an unsuccessful negotiation from the other end as a hint of a possibly -broken connection (5.5), -and adds sections on network partitions (5.4), -authentication methods and the subtleties of RSA public keys (6.7), -and miscellaneous interoperability concerns (6.8). -.H -1. Introduction -.P -The current IPsec specifications for key exchange and connection management, -RFCs 2408 [ISAKMP] and 2409 [IKE], -leave many aspects of connection management unspecified, -most prominently rekeying practices. -This is a cryptic puzzle which -each group of implementors has to struggle with, -and differences in how the ambiguities and gaps are resolved are -potentially a fruitful source of interoperability problems. -We can hope that future revisions of the specifications will clear this up. -Meanwhile, it seems useful to set down some successful experiences, -to minimize the extent to which new implementors have to rely -on unwritten folklore. -.P -The Linux FreeS/WAN implementation of IPsec interoperates -with almost every other IPsec implementation, -and because of its free nature, -it also sees some use as a reference implementation by other implementors. -The high degree of interoperability is noteworthy -given its organizers' strong minimalist bias, -which has caused them to implement only -a small subset of the full glory of IPsec. -This document describes how the FreeS/WAN project has resolved -some of the gaps in the IPsec specifications -(and plans to resolve some others), -and what difficulties have been encountered, -in hopes that this generally-successful experience -might be informative to new implementors. -.P -One small caution about applicability: -this experience may not be relevant -to severely resource-constrained implementations. -FreeS/WAN's target environment is previous-generation PCs, -now available at trivial cost (often, -within an organization, at no cost), -which have quite impressive CPU power and memory by the standards -of only a few years ago. -Some of the approaches discussed here may be inapplicable to -implementations with severe external constraints which prevent them -from taking advantage of modern hardware technology. -.H -2. Lower-level Background and Notes -.H -2.1. Packet Handling -.P -FreeS/WAN implements ESP [ESP] and AH [AH] straightforwardly, -although AH sees little use among our users. -Our ESP/AH implementation cannot currently handle packets -with IP options; -somewhat surprisingly, this has caused little difficulty. -We insist on encryption and do not support authentication-only -connections, and this has not caused significant difficulty either. -.P -MTU and fragmentation issues, by contrast, have been a constant headache. -We will not describe the details of our current approach to them, -because it still needs work. -One difficulty we have encountered is that many combinations of -packet source and packet destination -apparently cannot cope with an "interior minimum" in the path MTU, -e.g. where an IPsec tunnel intervenes and its headers reduce the MTU -for an intermediate link. -This is particularly prevalent when using common PC software to -connect to large well-known web sites; -we think it is largely due to -misconfigured firewalls which do not pass ICMP -Fragmentation Required messages. -The only solution we have yet found is to lie about the MTU of the tunnel, -accepting the (undesirable) fragmentation of the ESP packets -for the sake of preserving connectivity. -.P -We currently zero out the TOS field of ESP packets, -rather than copying it from the inner header, -on the grounds that it lends itself too well to traffic analysis -and covert channels. -We provide an option to restore RFC 2401 [IPSEC] copying behavior, -but this appears to see little use. -.H -2.2. Ciphers -.P -We initially implemented both DES [DES] and 3DES [CIPHERS] for both -IKE and ESP, -but after the Deep Crack effort [CRACK] demonstrated its inherent insecurity, -we dropped support for DES. -Somewhat surprisingly, -our insistence on 3DES has caused almost no interoperability problems, -despite DES being officially mandatory. -A very few other systems either do not support 3DES or support it only -as an optional upgrade, -which inconveniences a few would-be users. -There have also been one or two cases of systems -which don't quite seem to know the difference! -.P -See also section 6.1 for a consequence of our insistence on 3DES. -.H -2.3. Interfaces -.P -We currently employ PF_KEY version 2 [PFKEY], -plus various non-standard extensions, -as our interface between keying and ESP. -This has not proven entirely satisfactory. -Our feeling now is that keying issues and policy issues -do not really lend -themselves to the clean separation that PF_KEY envisions. -.H -3. IKE Infrastructural Issues -.P -A number of problems in IPsec connection management become easier if -some attention is first paid to providing an infrastructure -to support solving them. -.H -3.1. Continuous Channel -.P -FreeS/WAN uses an approximation to the "continuous channel" model, -in which ISAKMP SAs are maintained between IKEs -so long as any IPsec SAs are open between the two systems. -The resource consumption of this is minor: -the only substantial overhead is occasional rekeying. -IPsec SA management becomes significantly simpler if there is always -a channel for transmission of control messages. -We suggest (although we do not yet fully implement this) that -inability to maintain (e.g., to rekey) this control path -should be grounds for tearing down the IPsec SAs as well. -.P -As a corollary of this, -there is one and only one ISAKMP SA maintained between a pair of IKEs -(although see sections 5.3 and 6.5 for minor complications). -.H -3.2. Retransmission -.P -The unreliable nature of UDP transmission is a nuisance. -IKE implementations should always be prepared to retransmit the most recent -message they sent on an ISAKMP SA, -since there is some possibility that the other end did not get it. -This means, in particular, -that the system sending the supposedly-last message of an exchange -cannot relax and assume that the exchange is complete, -at least not until a significant timeout has elapsed. -.P -Systems must also retain information about the message most recently received -in an exchange, -so that a duplicate of it can be detected -(and possibly interpreted as a NACK for the response). -.P -The retransmission rules FreeS/WAN follows are: -(1) if a reply is expected, retransmit only if it does not appear -before a timeout; -and (2) if a reply is not expected (last message of the exchange), -retransmit only on receiving a retransmission of the previous message. -Notably, in case (1) we do NOT retransmit on receiving a retransmission, -which avoids possible congestion problems arising from packet duplication, -at the price of slowing response to packet loss. -The timeout for case (1) is 10 seconds for the first retry, -20 seconds for the second, and 40 seconds for all subsequent -retries (normally only one, -except when -configuration settings call for persistence and the message is -the first message of Main Mode with a new peer). -These retransmission rules have been entirely successful. -.P -(Michael Thomas of Cisco has pointed out that the retry timeouts should -include some random jitter, to de-synchronize hosts which are -initially synchronized by, e.g., a power outage. -We already jitter our rekeying times, -as noted in section 4.2, -but that does not help with initial startup. -We're implementing jittered retries, -but cannot yet report on experience with this.) -.P -There is a deeper problem, of course, when an entire "exchange" consists -of a single message, -e.g. the ISAKMP Informational Exchange. -Then there is no way to decide whether or when a retransmission is -warranted at all. -This seems like poor design, to put it mildly -(and there is now talk of fixing it). -We have no experience in dealing with this problem at this time, -although it is part of the reason why we have delayed implementing -Notification messages. -.H -3.3. Replay Prevention -.P -The unsequenced nature of UDP transmission is also troublesome, -because it means that higher levels must consider the possibility -of replay attacks. -FreeS/WAN takes the position that systematically eliminating this -possibility at a low level is strongly preferable to forcing careful -consideration of possible impacts at every step of an exchange. -RFC 2408 [ISAKMP] section 3.1 states that the Message ID of an -ISAKMP message must be "unique". -FreeS/WAN interprets this literally, -as forbidding duplication of Message IDs -within the set of all messages sent via a single ISAKMP SA. -.P -This requires remembering all Message IDs until the ISAKMP SA is -superseded by rekeying, -but that is not costly (four bytes per sent or received message), -and it ELIMINATES replay attacks from consideration; -we believe this investment of resources is well worthwhile. -If the resource consumption becomes excessive\(emin our experience -it has not\(emthe ISAKMP SA can be rekeyed early to collect the garbage. -.P -There is theoretically an interoperability problem when talking to -implementations which interpret "unique" more loosely -and may re-use Message IDs, -but it has not been encountered in practice. -This approach appears to be completely interoperable. -.P -The proposal by -Andrew Krywaniuk [REPLAY], -which advocates turning the Message ID into an anti-replay counter, -would achieve the same goal without the minor per-message memory overhead. -This may be preferable, -although it means an actual protocol change and more study is needed. -.H -4. Basic Keying and Rekeying -.H -4.1. When to Create SAs -.P -As Tim Jenkins [REKEY] pointed out, -there is a potential race condition in Quick Mode: -a fast lightly-loaded Initiator might start using IPsec SAs very -shortly after sending QM3 (the third and last message of Quick Mode), -while a slow heavily-loaded Responder might -not be ready to receive them until after spending -a significant amount of time creating its inbound SAs. -The problem is even worse if QM3 gets delayed or lost. -.P -FreeS/WAN's approach to this is what Jenkins called "Responder Pre-Setup": -the Responder creates its inbound IPsec SAs before it sends QM2, -so they are always ready and waiting -when the Initiator sends QM3 and begins sending traffic. -This approach is simple and reliable, -and in our experience it interoperates with everybody. -(There is potentially still a problem if FreeS/WAN is the Initiator -and the Responder does not use Responder Pre-Setup, -but no such problems have been seen.) -The only real weakness of Responder Pre-Setup -is the possibility of replay attacks, -which we have eliminated by other means (see section 3.3). -.P -With this approach, the Commit Bit is useless, -and we ignore it. -In fact, until quite recently we discarded any IKE message containing it, -and this caused surprisingly few interoperability problems; -apparently it is not widely used. -We have recently been persuaded that simply ignoring it is preferable; -preliminary experience with this indicates that the result is successful -interoperation with implementations which set it. -.H -4.2. When to Rekey -.P -To preserve connectivity for user traffic, -rekeying of a connection -(that is, creation of new IPsec SAs to supersede the current ones) -must begin before its current IPsec SAs expire. -Preferably one end should predictably start rekeying negotiations first, -to avoid the extra overhead of two simultaneous negotiations, -although either end should be prepared to rekey if the other does not. -There is also a problem with "convoys" of keying negotiations: -for example, a "hub" gateway with many IPsec connections -can be inundated with rekeying negotiations -exactly one connection-expiry time after it reboots, -and the massive overload this induces tends to make this -situation self-perpetuating, -so it recurs regularly. -(Convoys can also evolve gradually from initially-unsynchronized negotiations.) -.P -FreeS/WAN has the concept of a "rekeying margin", measured in seconds. -If FreeS/WAN was the Initiator for the previous rekeying -(or the startup, if none) of the connection, -it nominally starts rekeying negotiations at expiry time -minus one rekeying margin. -Some random jitter is added to break up convoys: -rather than starting rekeying exactly at minus one margin, -it starts at a random time between minus one margin -and minus two margins. -(The randomness here need not be cryptographic in quality, -so long as it varies over time and between hosts. -We use an ordinary PRNG seeded with a few bytes from a cryptographic -randomness source. -The seeding mostly just ensures that the PRNG sequence is different -for different hosts, even if they start up simultaneously.) -.P -If FreeS/WAN was the Responder for the previous rekeying/startup, -and nothing has been heard from the previous Initiator -at expiry time minus one-half the rekeying margin, -FreeS/WAN will initiate rekeying negotiations. -No jitter is applied; -we now believe that it should be jittered, -say between minus one-half margin and minus one-quarter margin. -.P -Having the Initiator lead the way is an obvious way of deciding -who should speak first, -since there is already an Initiator/Responder asymmetry in the connection. -Moreover, our experience has been that Initiator lead gives a significantly -higher probability of successful negotiation! -The negotiation process itself is asymmetric, -because the Initiator must make a few specific proposals which the Responder -can only accept or reject, -so the Initiator must try to guess where its "acceptable" region -(in parameter space) -might overlap with the Responder's. -We have seen situations where negotiations would succeed or fail -depending on which end initiated them, -because one end was making better guesses. -Given an existing connection, -we KNOW that the previous Initiator WAS able to initiate a successful -negotiation, -so it should (if at all possible) take the lead again. -Also, the Responder should remember the Initiator's successful proposal, -and start from that -rather than from his own default proposals if he must take the lead; -we don't currently implement this completely but plan to. -.P -FreeS/WAN defaults the rekeying margin to 9 minutes, -although this can be changed by configuration. -There is also -a configuration option to alter the permissible range of jitter. -The defaults were chosen somewhat arbitrarily, -but they work extremely well -and the configuration options are rarely used. -.H -4.3. Choosing an SA -.P -Once rekeying has occurred, -both old and new IPsec SAs for the connection exist, -at least momentarily. -FreeS/WAN accepts incoming traffic -on either old or new inbound SAs, -but sends outgoing traffic only on the new outbound ones. -This approach appears to be significantly more robust than -using the old ones until they expire, -notably in cases where renegotiation has occurred because something has -gone wrong on the other end. -It avoids having to pay meticulous attention to the state of the other end, -state which is difficult to learn reliably given the limitations of IKE. -.P -This approach has interoperated successfully with ALMOST all other -implementations. -The only (well-characterized) problem cases have been implementations -which rely on receiving a Delete message for the old SAs to tell them -to switch over to the new ones. -Since delivery of Delete is unreliable, -and support for Delete is optional, -this reliance seems like a serious mistake. -This is all the more true because Delete -announces that the deletion has -already occurred [ISAKMP, section 3.15], not that it is about to occur, -so packets already in transit in the other direction could be lost. -Delete should be used for resource cleanup, not for switchover control. -(These matters are discussed further in section 5.) -.H -4.4. Why to Rekey -.P -FreeS/WAN currently implements only time-based expiry (life in seconds), -although we are working toward -supporting volume-based expiry (life in kilobytes) as well. -The lack of volume-based expiry has not been an interoperability -problem so far. -.P -Volume-based expiry does add some minor complications. -In particular, it makes explicit Delete of now-disused SAs more important, -because once an SA stops being used, -it might not expire on its own. -We believe this lacks robustness and is generally unwise, -especially given the lack of a reliable Delete, -and expect to use volume-based expiry only as a supplement -to time-based expiry. -However, Delete support (see section 5) does seem advisable -for use with volume-based expiry. -.P -We do not believe that volume-based expiry alters the desirability -of switching immediately to the new SAs after rekeying. -Rekeying margins are normally a small fraction of the total life of an SA, -so we feel there is no great need to "use it all up". -.H -4.5. Rekeying ISAKMP SAs -.P -The above discussion has focused on rekeying for IPsec SAs, -but FreeS/WAN applies the same approaches to rekeying for ISAKMP SAs, -with similar success. -.P -One issue which we have noticed, but not explicitly dealt with, -is that difficulties may ensue if an IPsec-SA rekeying negotiation -is in progress at the time when the relevant ISAKMP SA gets rekeyed. -The IKE specification [IKE] hints, but does not actually say, -that a Quick Mode negotiation should remain on a single ISAKMP SA throughout. -.P -A reasonable rekeying margin will generally -prevent the old ISAKMP SA from actually expiring during a negotiation. -Some attention may be needed to prevent in-progress negotiations from -being switched to the new ISAKMP SA. -Any attempt at pre-expiry deletion of the ISAKMP SA must be postponed -until after such dangling negotiations are completed, -and there should be enough delay between ISAKMP-SA rekeying and a -deletion attempt to (more or less) -ensure that there are no negotiation-starting packets still in transit -from before the rekeying. -.P -At present, FreeS/WAN does none of this, -and we don't KNOW of any resulting trouble. -With normal lifetimes, the problem should be uncommon, -and we speculate that an occasional disrupted negotiation simply gets retried. -.H -4.6. Bulk Negotiation -.P -Quick Mode nominally provides for negotiating possibly-large numbers of -similar but unrelated IPsec SAs simultaneously -[IKE, section 9]. -Nobody appears to do this. -FreeS/WAN does not support it, and its absence has caused no problems. -.H -5. Deletions, Teardowns, Crashes -.P -FreeS/WAN currently ignores all Notifications and Deletes, -and never generates them. -This has caused little difficulty in interoperability, -which shouldn't be surprising (since Notification and Delete support is -officially entirely optional) but does seem to surprise some people. -Nevertheless, we do plan some changes to this approach -based on past experience. -.H -5.1. Deletions -.P -As hinted at above, -we plan to implement Delete support, done as follows. -Shortly after rekeying of IPsec SAs, -the Responder issues a Delete for its old inbound SAs -(but does not actually delete them yet). -The Responder initiates this because the Initiator started using the -new SAs on sending QM3, while the Responder started using them only -on (or somewhat after) receiving QM3, -so there is less chance of old-SA packets still being in transit from -the Initiator. -The Initiator issues an unsolicited Delete only if it does not hear one -from the Responder after a longer delay. -.P -Either party, on receiving a Delete -for one or more of the old outbound SAs of a connection, -deletes ALL the connection's SAs, -and acknowledges with a Delete for the old inbound SAs. -A Delete for nonexistent SAs -(e.g., SAs which have already been expired or deleted) is ignored. -There is no retransmission of unacknowledged Deletes. -.P -In the normal case, -with prompt reliable transmission (except possibly for loss of the -Responder's initial Delete) -and conforming implementations -on both ends, this results in three Deletes being transmitted, -resembling the classic three-way handshake. -Loss of a Delete after the first, or multiple losses, -will cause the SAs not to be deleted on at least one end. -It appears difficult to do much better without at least -a distinction between request and acknowledgement. -.P -RFC 2409 section 9 "strongly suggests" that there be no response to -informational messages such as Deletes, -but the only rationale offered is prevention of infinite loops -endlessly exchanging "I don't understand you" informationals. -Since Deletes cannot lead to such a loop -(and in any case, the nonexistent-SA rule prevents more than one -acknowledgement for the same connection), -we believe this recommendation is inapplicable here. -.P -As noted in section 4.3, these Deletes are intended for -resource cleanup, not to control switching between SAs. -But we expect that they will improve interoperability -with some broken implementations. -.P -We believe strongly that connections need to be considered as a whole, -rather than treating each SA as an independent entity. -We will issue Deletes only for the full set of inbound SAs of -a connection, -and will treat a Delete for any outbound SA as equivalent to deletion -of all the outbound SAs for the associated connection. -.P -The above is phrased in terms of IPsec SAs, -but essentially the same approach can be applied to ISAKMP SAs -(the Deletes for the old ISAKMP SA should be sent via the new one). -.H -5.2. Teardowns and Shutdowns -.P -When a connection is not intended to be up permanently, -there is a need to coordinate teardown, -so that both ends are aware that the connection is down. -This is both for recovery of resources, -and to avoid routing packets through -dangling SAs which can no longer deliver them. -.P -Connection teardown will use the same bidirectional exchange of Deletes -as discussed in section 5.1: -a Delete received for current IPsec SAs (not yet obsoleted by rekeying) -indicates that the other host wishes to tear down the associated connection. -.P -A Delete received for a current ISAKMP SA indicates that the other host -wishes to tear down not only the ISAKMP SA but also all IPsec SAs -currently under the supervision of that ISAKMP SA. -The 5.1 bidirectional exchange might seem impossible in this case, -since reception of an ISAKMP-SA Delete indicates that the other end -will ignore further traffic on that ISAKMP SA. -We suggest using the same tactic discussed in 5.1 for IPsec SAs: -the first Delete is sent without actually doing the deletion, -and the response to receiving a Delete is to do the deletion and reply -with another Delete. -If there is no response to the first Delete, -retry a small number of times and then give up and do the deletion; -apart from being robust against packet loss, -this also maximizes the probability that an implementation which does -not do the bidirectional Delete will receive at least one of the Deletes. -.P -When a host with current connections knows that it is about to shut down, -it will issue Deletes for all SAs involved (both IPsec and ISAKMP), -advising its peers (as per the meaning of Delete [ISAKMP, section 3.15]) -that the SAs have become useless. -It will ignore attempts at rekeying or connection startup thereafter, -until it shuts down. -.P -It would be better to have a Final-Contact notification, -analogous to Initial-Contact but indicating that no new negotiations -should be attempted until further notice. -Initial-Contact actually could be used for shutdown notification (!), -but in networks where connections are intended to exist permanently, -it seems likely to provoke unwanted attempts -to renegotiate the lost connections. -.H -5.3. Crashes -.P -Systems sometimes crash. -Coping with the resulting loss of information is easily the most -difficult problem we have found in implementing robust IPsec systems. -.P -When connections are intended to be permanent, -it is simple to specify renegotiation on reboot. -With our approach to SA selection (see section 4.3), -this handles such cases robustly and well. -We do have to tell users that BOTH hosts should be set this way. -In cases where crashes are synchronized (e.g. by power interruptions), -this may result in simultaneous negotiations at reboot. -We currently allow both negotiations to proceed to completion, -but our use-newest selection method -effectively ignores one connection or the other, -and when one of them rekeys, -we notice that the new SAs replace those of both old connections, -and we then refrain from rekeying the other. -(This duplicate detection is desirable in any event, for robustness, -to ensure that the system converges on a reasonable state eventually -after it is perturbed by difficulties or bugs.) -.P -When connections are not permanent, the situation is less happy. -One particular situation in which we see problems is when a number of -"Road Warrior" hosts occasionally call in to a central server. -The server is normally configured not to initiate such connections, -since it does not know when the Road Warrior is available (or what IP -address it is using). -Unfortunately, if the server crashes and reboots, -any Road Warriors then connected have a problem: -they don't know that the server has crashed, -so they can't renegotiate, -and the server has forgotten both the connections and -their (transient) IP addresses, -so it cannot renegotiate. -.P -We believe that the simplest answer to this problem is what John Denker -has dubbed "address inertia": -the server makes a best-effort attempt to remember (in nonvolatile storage) -which connections were active and what the far-end addresses were -(and what the successful proposal's parameters were), -so that it can attempt renegotiation on reboot. -We have not implemented this yet, but intend to; -Denker has implemented it himself, -although in a somewhat messy way, -and reports excellent results. -.H -5.4. Network Partitions -.P -A network partition, making the two ends unable to reach each other, -has many of the same characteristics as having the other end crash... until -the network reconnects. -It is desirable that recovery from this be automatic. -.P -If the network reconnects before any rekeying attempts -or other IKE activities occurred, -recovery is fully transparent, -because the IKEs have no idea that there was any problem. -(Complaints such as ICMP Host Unreachable messages are unauthenticated -and hence cannot be given much weight.) -This fits the general mold of TCP/IP: -if nobody wanted to send any traffic, a network outage doesn't matter. -.P -If IKE activity did occur, -the IKE implementation will discover that the other end doesn't seem -to be responding. -The preferred response to this depends on the nature of the connection. -If it was intended to be ephemeral (e.g. opportunistic encryption [OE]), -closing it down after a few retries is reasonable. -If the other end is expected to sometimes drop the connection without -warning, it may not be desirable to retry at all. -(We support both these forms of configurability, -and indeed we also have a configuration option to suppress -rekeying entirely on one end.) -.P -If the connection was intended to be permanent, however, -then persistent attempts to re-establish it are appropriate. -Some degree of backoff is appropriate here, -so that retries get less frequent as the outage gets prolonged. -Backoff should be limited, -so that re-established connectivity is not followed by a long delay -before a retry. -Finally, after many retries (say 24 hours' worth), -it may be preferable to just declare the connection down and rely -on manual intervention to re-establish it, -should this be desirable. -We do not yet fully support all this. -.H -5.5. Unknown SAs -.P -A more complete solution to crashes -would be for an IPsec host to note the arrival -of ESP packets on an unknown IPsec SA, -and report it somehow to the other host, which can then decide to renegotiate. -This arguably might be preferable in any case\(emif -the non-rebooted host has no traffic to send, -it does not care whether the connection is intact\(embut -delays and packet loss will be reduced -if the connection is renegotiated BEFORE there is traffic for it. -So unknown-SA detection is best reserved as a fallback method, -with address inertia used to deal with most such cases. -.P -A difficulty with unknown-SA detection is, -just HOW should the other host be notified? -IKE provides no good way to do the notification: -Notification payloads (e.g., Initial-Contact) are unauthenticated -unless they are sent under protection of an ISAKMP SA. -A "Security Failures - Bad SPI" ICMP message [SECFAIL] -is an interesting alternative, -but has the disadvantage of likewise being unauthenticated. -It's fundamentally unlikely that there is a simple solution to this, -given that almost any way of arranging or checking authentication for such a -notification is costly. -.P -We think the best answer to this is a two-step approach. -An unauthenticated Initial-Contact or -Security Failures - Bad SPI cannot be taken as a reliable -report of a problem, -but can be taken as a hint that a problem MIGHT exist. -Then there needs to be some reliable way of checking such hints, -subject to rate limiting since the checks are likely to be costly -(and checking the same connection repeatedly at short intervals is unlikely -to be worthwhile anyway). -So the rebooted host sends the notification, -and the non-rebooted host\(emwhich still thinks it has a connection\(emchecks -whether the connection still works, -and renegotiates if not. -.P -Also, if an IPsec host which believes it has a connection to another host -sees an unsuccessful attempt by that host to negotiate a new one, -that is also a hint of possible problems, -justifying a check and possible renegotiation. -("Unsuccessful" here means a negotiation failure due to lack of a -satisfactory proposal. -A failure due to authentication failure -suggests a denial-of-service attack by a third party, -rather than a genuine problem on the legitimate other end.) -As noted in section 4.2, -it is possible for negotiations to succeed or fail based on which -end initiates them, and some robustness against that is desirable. -.P -We have not yet decided what form the notification should take. -IKE Initial-Contact is an obvious possibility, -but has some disadvantages. -It does not specify which connection has had difficulties. -Also, the specification [IKE section 4.6.3.3] -refers to "remote system" and "sending system" -without clearly specifying just what "system" means; -in the case of a multi-homed host using multiple forms of identification, -the question is not trivial. -Initial-Contact does have the fairly-decisive advantage -that it is likely to convey the right general -meaning even to an implementation which does not do things -exactly the way ours does. -.P -A more fundamental difficulty is what form the reliable check takes. -What is wanted is an "IKE ping", -verifying that the ISAKMP SA is still intact -(it being unlikely that IPsec SAs have been lost while the ISAKMP SA has not). -The lack of such a facility is a serious failing of IKE. -An acknowledged Notification of some sort would be ideal, -but there is none at present. -Some existing implementations are known -to use the private Notification values 30000 as ping -and 30002 as ping reply, -and that seems the most attractive choice at present. -If it is not recognized, there will probably be no reply, -and the result will be an unnecessary renegotiation, -so this needs strict rate limiting. -(Also, when a new connection is set up, -it's probably worth determining by experiment whether the other end -supports IKE ping, and remembering that.) -.P -While we think this facility is desirable, -and is about the best that can be done with the poor tools available, -we have not gotten very far in implementation and cannot comment -intelligently about how well it works or interoperates. -.H -6. Misc. IKE Issues -.H -6.1. Groups 1 and 5 -.P -We have dropped support for the first Oakley Group (group 1), -despite it being officially mandatory, -on the grounds that it is -grossly too weak to provide enough randomness for 3DES. -There have been some interoperability problems, -mostly quite minor: -ALMOST everyone supports group 2 as well, -although sometimes it has to be explicitly configured. -.P -We also support the quasi-standard group 5 [GROUPS]. -This has not been seriously exercised yet, -because historically -we offered group 2 first and almost everyone accepted it. -We have recently changed to offering group 5 first, -and no difficulties have been reported. -.H -6.2. To PFS Or Not To PFS -.P -A persistent small interoperability problem is that -the presence or absence of PFS (for keys [IKE, section 5.5]) -is neither negotiated nor announced. -We have it enabled by default, -and successful interoperation often requires having -the other end turn it on in their implementation, -or having the FreeS/WAN end disable it. -Almost everyone supports it, but it's usually not the default, -and interoperability is often impossible unless the two ends -somehow reach prior agreement on it. -.P -We do not explicitly support the other flavor of PFS, -for identities [IKE, section 8], -and this has caused no interoperability problems. -.H -6.3. Debugging Tools, Lack Thereof -.P -We find IKE lacking in basic debugging tools. -Section 5.4, above, -notes that an IKE ping would be useful for connectivity verification. -It would also be extremely helpful for determining that UDP/500 -packets get back and forth successfully between the two ends, -which is often an important first step in debugging. -.P -It's also quite common to have IKE negotiate a connection successfully, -but to have some firewall along the way blocking ESP. -Users find this mysterious and difficult to diagnose. -We have no immediate suggestions on what could be done about it. -.H -6.4. Terminology, Vagueness Thereof -.P -The terminology of IPsec needs work. -We feel that both the specifications and user-oriented -documentation would be greatly clarified by concise, intelligible names for -certain concepts. -.P -We semi-consistently use "group" for the set of IPsec SAs which are -established in one direction -by a single Quick Mode negotiation and are used together -to process a packet (e.g., an ESP SA plus an AH SA), -"connection" for the logical packet path provided -by a succession of pairs of groups -(each rekeying providing a new pair, one group in each direction), -and "keying channel" for the corresponding supervisory path provided -by a sequence of ISAKMP SAs. -.P -We think it's a botch that "PFS" is used to refer to two very different things, -but we have no specific new terms to suggest, since we only implement -one kind of PFS and thus can just ignore the other. -.H -6.5. A Question of Identity -.P -One specification problem deserves note: -exactly when can an existing phase 1 negotiation -be re-used for a new phase 2 negotiation, -as IKE [IKE, section 4] specifies? -Presumably, -when it connects the same two "parties"... but exactly what is a "party"? -.P -As noted in section 5.4, -in cases involving multi-homing and multiple identities, -it's not clear exactly what criteria are used for deciding -whether the intended far end for a new negotiation is the same one -as for a previous negotiation. -Is it by Identification Payload? -By IP address? -Or what? -.P -We currently use a somewhat-vague notion of "identity", -basically what gets sent in Identification Payloads, -for this, and this seems to be successful, -but we think this needs better specification. -.H -6.6. Opportunistic Encryption -.P -Further IKE challenges appear in the context of Opportunistic Encryption -[OE], -but operational experience with it is too limited as yet for us -to comment usefully right now. -.H -6.7. Authentication and RSA Keys -.P -We provide two IKE authentication methods: -shared secrets ("pre-shared keys") -and RSA digital signatures. -(A user-provided add-on package generalizes the latter to limited -support for certificates; -we have not worked extensively with it ourselves yet and cannot comment -on it yet.) -.P -Shared secrets, despite their administrative difficulties, -see considerable use, -and are also the method of last resort for interoperability problems. -.P -For digital signatures, -we have taken the somewhat unorthodox approach of using "bare" RSA public keys, -either supplied in configuration files or fetched from DNS, -rather than getting involved in the complexity of certificates. -We encode our RSA public keys using the DNS KEY encoding [DNSRSA] -(aka "RFC 2537", although that RFC is now outdated), -which has given us no difficulties and which we highly recommend. -We have seen two difficulties in connection with RSA keys, however. -.P -First, -while a number of IPsec implementations are able to take "bare" RSA public keys, -each one seems to have its own idea of what format should be used -for transporting them. -We've had little success with interoperability here, -mostly because of key-format issues; -the implementations generally WILL interoperate successfully if you can -somehow get an RSA key into them at all, but that's hard. -X.509 certificates seem to be the lowest (!) -common denominator for key transfer. -.P -Second, -although the content of RSA public keys has been stable, -there has been a small but subtle change over time in the content -of RSA private keys. -The "internal modulus", -used to compute the private exponent "d" from the public exponent "e" -(or vice-versa) -was originally [RSA] [PKCS1v1] [SCHNEIER] specified to be (p-1)*(q-1), -where p and q are the two primes. -However, more recent definitions [PKCS1v2] call it -"lambda(n)" and define it to be lcm(p-1,\ q-1); -this appears to be a minor optimization. -The result is that private keys generated with the new definition -often fail consistency checks in implementations using the old definition. -Fortunately, it is seldom necessary to move private keys around. -Our software now consistently uses the new definition -(and thus will accept keys generated with either definition), -but our key generator also has an option to generate old-definition keys, -for the benefit of users who upgrade their networks incrementally. -.H -6.8. Misc. Snags -.P -Nonce size is another characteristic that is neither negotiated nor announced -but that the two ends must somehow be able to agree on. -Our software accepts anything between 8 and 256, and defaults to 16. -These numbers were chosen rather arbitrarily, -but we have seen no interoperability failures here. -.P -Nothing in the ISAKMP [ISAKMP] or IKE [IKE] specifications says -explicitly that a normal Message ID must be non-zero, -but a zero Message ID in fact causes failures. -.P -Similarly, there is nothing in the specs which says that ISAKMP cookies -must be non-zero, but zero cookies will in fact cause trouble. -.H -7. Security Considerations -.P -Since this document discusses aspects of building robust and -interoperable IPsec implementations, -security considerations permeate it. -.H -8. References -.R AH -Kent, S., and Atkinson, R., -"IP Authentication Header", -RFC 2402, -Nov 1998. -.R CIPHERS -Pereira, R., and Adams, R., -"The ESP CBC-Mode Cipher Algorithms", -RFC 2451, -Nov 1998. -.R CRACK -Electronic Frontier Foundation, -"Cracking DES: -Secrets of Encryption Research, Wiretap Politics and Chip Design", -O'Reilly 1998, -ISBN 1-56592-520-3. -.R DES -Madson, C., and Doraswamy, N., -"The ESP DES-CBC Cipher Algorithm", -RFC 2405, -Nov 1998. -.R DNSRSA -D. Eastlake 3rd, -"RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)", -RFC 3110, -May 2001. -.R ESP -Kent, S., and Atkinson, R., -"IP Encapsulating Security Payload (ESP)", -RFC 2406, -Nov 1998. -.R GROUPS -Kivinen, T., and Kojo, M., -"More MODP Diffie-Hellman groups for IKE", -, -13 Dec 2001 (work in progress). -.R IKE -Harkins, D., and Carrel, D., -"The Internet Key Exchange (IKE)", -RFC 2409, Nov 1998. -.R IPSEC -Kent, S., and Atkinson, R., -"Security Architecture for the Internet Protocol", -RFC 2401, Nov 1998. -.R ISAKMP -Maughan, D., Schertler, M., Schneider, M., and Turner, J., -"Internet Security Association and Key Management Protocol (ISAKMP)", -RFC 2408, Nov 1998. -.R OE -Richardson, M., Redelmeier, D. H., and Spencer, H., -"A method for doing opportunistic encryption with IKE", -, -21 Feb 2002 (work in progress). -.R PKCS1v1 -Kaliski, B., -"PKCS #1: RSA Encryption, Version 1.5", -RFC 2313, March 1998. -.R PKCS1v2 -Kaliski, B., and Staddon, J., -"PKCS #1: RSA Cryptography Specifications, Version 2.0", -RFC 2437, Oct 1998. -.R PFKEY -McDonald, D., Metz, C., and Phan, B., -"PF_KEY Key Management API, Version 2", -RFC 2367, July 1998. -.R REKEY -Tim Jenkins, "IPsec Re-keying Issues", -, -2 May 2000 (draft expired, work no longer in progress). -.R REPLAY -Krywaniuk, A., -"Using Isakmp Message Ids for Replay Protection", -, -9 July 2001 -(work in progress). -.R RSA -Rivest, R.L., Shamir, A., and Adleman, L., -"A Method for Obtaining Digital Signatures and Public-Key -Cryptosystems", -Communications of the ACM v21n2, Feb 1978, p. 120. -.R SCHNEIER -Bruce Schneier, "Applied Cryptography", 2nd ed., -Wiley 1996, ISBN 0-471-11709-9. -.R SECFAIL -Karn, P., and Simpson, W., -"ICMP Security Failures Messages", -RFC 2521, -March 1999. -.H -Authors' Addresses -.P -.nf -.ne 8 -Henry Spencer -SP Systems -Box 280 Stn. A -Toronto, Ont. M5W1B2 -Canada - -henry@spsystems.net -416-690-6561 -.ne 8 -.sp 2 -D. Hugh Redelmeier -Mimosa Systems Inc. -29 Donino Ave. -Toronto, Ont. M4N2W6 -Canada - -hugh@mimosa.com -416-482-8253 -.bp -.H -Full Copyright Statement -.P -Copyright (C) The Internet Society \*c. All Rights -Reserved. - -This document and translations of it may be copied and -furnished to others, and derivative works that comment on or -otherwise explain it or assist in its implmentation may be -prepared, copied, published and distributed, in whole or in -part, without restriction of any kind, provided that the above -copyright notice and this paragraph are included on all such -copies and derivative works. However, this document itself may -not be modified in any way, such as by removing the copyright -notice or references to the Internet Society or other Internet -organizations, except as needed for the purpose of developing -Internet standards in which case the procedures for copyrights -defined in the Internet Standards process must be followed, or -as required to translate it into languages other than English. - -The limited permissions granted above are perpetual and will -not be revoked by the Internet Society or its successors or -assigns. - -This document and the information contained herein is provided -on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET -ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE -OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY -IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A -PARTICULAR PURPOSE. diff --git a/doc/draft-spencer-ipsec-ike-implementation.txt b/doc/draft-spencer-ipsec-ike-implementation.txt deleted file mode 100644 index 145c00ba8..000000000 --- a/doc/draft-spencer-ipsec-ike-implementation.txt +++ /dev/null @@ -1,1232 +0,0 @@ - - - -Network Working Group Henry Spencer -Internet Draft SP Systems -Expires: 26 Aug 2002 D. Hugh Redelmeier - Mimosa Systems - 26 Feb 2002 - - IKE Implementation Issues - - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - (If approved as an Informational RFC...) This memo provides - information for the Internet community. This memo does not specify - an Internet standard of any kind. - - Distribution of this memo is unlimited. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on 26 Aug 2002. - -Copyright Notice - - Copyright (C) The Internet Society 2002. All Rights Reserved. - - - - - - - - - - -Spencer & Redelmeier [Page 1] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - -Table of Contents - - 1. Introduction ................................................... 3 - 2. Lower-level Background and Notes ............................... 4 - 2.1. Packet Handling .............................................. 4 - 2.2. Ciphers ...................................................... 5 - 2.3. Interfaces ................................................... 5 - 3. IKE Infrastructural Issues ..................................... 5 - 3.1. Continuous Channel ........................................... 5 - 3.2. Retransmission ............................................... 5 - 3.3. Replay Prevention ............................................ 6 - 4. Basic Keying and Rekeying ...................................... 7 - 4.1. When to Create SAs ........................................... 7 - 4.2. When to Rekey ................................................ 8 - 4.3. Choosing an SA ............................................... 9 - 4.4. Why to Rekey ................................................. 9 - 4.5. Rekeying ISAKMP SAs ......................................... 10 - 4.6. Bulk Negotiation ............................................ 10 - 5. Deletions, Teardowns, Crashes ................................. 11 - 5.1. Deletions ................................................... 11 - 5.2. Teardowns and Shutdowns ..................................... 12 - 5.3. Crashes ..................................................... 13 - 5.4. Network Partitions .......................................... 13 - 5.5. Unknown SAs ................................................. 14 - 6. Misc. IKE Issues .............................................. 16 - 6.1. Groups 1 and 5 .............................................. 16 - 6.2. To PFS Or Not To PFS ........................................ 16 - 6.3. Debugging Tools, Lack Thereof ............................... 16 - 6.4. Terminology, Vagueness Thereof .............................. 17 - 6.5. A Question of Identity ...................................... 17 - 6.6. Opportunistic Encryption .................................... 17 - 6.7. Authentication and RSA Keys ................................. 17 - 6.8. Misc. Snags ................................................. 18 - 7. Security Considerations ....................................... 19 - 8. References .................................................... 19 - Authors' Addresses ............................................... 20 - Full Copyright Statement ......................................... 21 - - - - - - - - - - - - - - -Spencer & Redelmeier [Page 2] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - -Abstract - - The current IPsec specifications for key exchange and connection - management, RFCs 2408 [ISAKMP] and 2409 [IKE], leave many aspects of - connection management unspecified, most prominently rekeying - practices. Pending clarifications in future revisions of the - specifications, this document sets down some successful experiences, - to minimize the extent to which new implementors have to rely on - unwritten folklore. - - The Linux FreeS/WAN implementation of IPsec interoperates with almost - every other IPsec implementation. This document describes how the - FreeS/WAN project has resolved some of the gaps in the IPsec - specifications (and plans to resolve some others), and what - difficulties have been encountered, in hopes that this generally- - successful experience might be informative to new implementors. - - This is offered as an Informational RFC. - - This -02 revision mainly: discusses ISAKMP SA expiry during IPsec-SA - rekeying (4.5), revises the discussion of bidirectional Deletes - (5.1), suggests remembering the parameters of successful negotiations - for later use (4.2, 5.3), notes an unsuccessful negotiation from the - other end as a hint of a possibly broken connection (5.5), and adds - sections on network partitions (5.4), authentication methods and the - subtleties of RSA public keys (6.7), and miscellaneous - interoperability concerns (6.8). - -1. Introduction - - The current IPsec specifications for key exchange and connection - management, RFCs 2408 [ISAKMP] and 2409 [IKE], leave many aspects of - connection management unspecified, most prominently rekeying - practices. This is a cryptic puzzle which each group of implementors - has to struggle with, and differences in how the ambiguities and gaps - are resolved are potentially a fruitful source of interoperability - problems. We can hope that future revisions of the specifications - will clear this up. Meanwhile, it seems useful to set down some - successful experiences, to minimize the extent to which new - implementors have to rely on unwritten folklore. - - The Linux FreeS/WAN implementation of IPsec interoperates with almost - every other IPsec implementation, and because of its free nature, it - also sees some use as a reference implementation by other - implementors. The high degree of interoperability is noteworthy - given its organizers' strong minimalist bias, which has caused them - to implement only a small subset of the full glory of IPsec. This - document describes how the FreeS/WAN project has resolved some of the - - - -Spencer & Redelmeier [Page 3] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - gaps in the IPsec specifications (and plans to resolve some others), - and what difficulties have been encountered, in hopes that this - generally-successful experience might be informative to new - implementors. - - One small caution about applicability: this experience may not be - relevant to severely resource-constrained implementations. - FreeS/WAN's target environment is previous-generation PCs, now - available at trivial cost (often, within an organization, at no - cost), which have quite impressive CPU power and memory by the - standards of only a few years ago. Some of the approaches discussed - here may be inapplicable to implementations with severe external - constraints which prevent them from taking advantage of modern - hardware technology. - -2. Lower-level Background and Notes - -2.1. Packet Handling - - FreeS/WAN implements ESP [ESP] and AH [AH] straightforwardly, - although AH sees little use among our users. Our ESP/AH - implementation cannot currently handle packets with IP options; - somewhat surprisingly, this has caused little difficulty. We insist - on encryption and do not support authentication-only connections, and - this has not caused significant difficulty either. - - MTU and fragmentation issues, by contrast, have been a constant - headache. We will not describe the details of our current approach - to them, because it still needs work. One difficulty we have - encountered is that many combinations of packet source and packet - destination apparently cannot cope with an "interior minimum" in the - path MTU, e.g. where an IPsec tunnel intervenes and its headers - reduce the MTU for an intermediate link. This is particularly - prevalent when using common PC software to connect to large well- - known web sites; we think it is largely due to misconfigured - firewalls which do not pass ICMP Fragmentation Required messages. - The only solution we have yet found is to lie about the MTU of the - tunnel, accepting the (undesirable) fragmentation of the ESP packets - for the sake of preserving connectivity. - - We currently zero out the TOS field of ESP packets, rather than - copying it from the inner header, on the grounds that it lends itself - too well to traffic analysis and covert channels. We provide an - option to restore RFC 2401 [IPSEC] copying behavior, but this appears - to see little use. - - - - - - -Spencer & Redelmeier [Page 4] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - -2.2. Ciphers - - We initially implemented both DES [DES] and 3DES [CIPHERS] for both - IKE and ESP, but after the Deep Crack effort [CRACK] demonstrated its - inherent insecurity, we dropped support for DES. Somewhat - surprisingly, our insistence on 3DES has caused almost no - interoperability problems, despite DES being officially mandatory. A - very few other systems either do not support 3DES or support it only - as an optional upgrade, which inconveniences a few would-be users. - There have also been one or two cases of systems which don't quite - seem to know the difference! - - See also section 6.1 for a consequence of our insistence on 3DES. - -2.3. Interfaces - - We currently employ PF_KEY version 2 [PFKEY], plus various non- - standard extensions, as our interface between keying and ESP. This - has not proven entirely satisfactory. Our feeling now is that keying - issues and policy issues do not really lend themselves to the clean - separation that PF_KEY envisions. - -3. IKE Infrastructural Issues - - A number of problems in IPsec connection management become easier if - some attention is first paid to providing an infrastructure to - support solving them. - -3.1. Continuous Channel - - FreeS/WAN uses an approximation to the "continuous channel" model, in - which ISAKMP SAs are maintained between IKEs so long as any IPsec SAs - are open between the two systems. The resource consumption of this - is minor: the only substantial overhead is occasional rekeying. - IPsec SA management becomes significantly simpler if there is always - a channel for transmission of control messages. We suggest (although - we do not yet fully implement this) that inability to maintain (e.g., - to rekey) this control path should be grounds for tearing down the - IPsec SAs as well. - - As a corollary of this, there is one and only one ISAKMP SA - maintained between a pair of IKEs (although see sections 5.3 and 6.5 - for minor complications). - -3.2. Retransmission - - The unreliable nature of UDP transmission is a nuisance. IKE - implementations should always be prepared to retransmit the most - - - -Spencer & Redelmeier [Page 5] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - recent message they sent on an ISAKMP SA, since there is some - possibility that the other end did not get it. This means, in - particular, that the system sending the supposedly-last message of an - exchange cannot relax and assume that the exchange is complete, at - least not until a significant timeout has elapsed. - - Systems must also retain information about the message most recently - received in an exchange, so that a duplicate of it can be detected - (and possibly interpreted as a NACK for the response). - - The retransmission rules FreeS/WAN follows are: (1) if a reply is - expected, retransmit only if it does not appear before a timeout; and - (2) if a reply is not expected (last message of the exchange), - retransmit only on receiving a retransmission of the previous - message. Notably, in case (1) we do NOT retransmit on receiving a - retransmission, which avoids possible congestion problems arising - from packet duplication, at the price of slowing response to packet - loss. The timeout for case (1) is 10 seconds for the first retry, 20 - seconds for the second, and 40 seconds for all subsequent retries - (normally only one, except when configuration settings call for - persistence and the message is the first message of Main Mode with a - new peer). These retransmission rules have been entirely successful. - - (Michael Thomas of Cisco has pointed out that the retry timeouts - should include some random jitter, to de-synchronize hosts which are - initially synchronized by, e.g., a power outage. We already jitter - our rekeying times, as noted in section 4.2, but that does not help - with initial startup. We're implementing jittered retries, but - cannot yet report on experience with this.) - - There is a deeper problem, of course, when an entire "exchange" - consists of a single message, e.g. the ISAKMP Informational Exchange. - Then there is no way to decide whether or when a retransmission is - warranted at all. This seems like poor design, to put it mildly (and - there is now talk of fixing it). We have no experience in dealing - with this problem at this time, although it is part of the reason why - we have delayed implementing Notification messages. - -3.3. Replay Prevention - - The unsequenced nature of UDP transmission is also troublesome, - because it means that higher levels must consider the possibility of - replay attacks. FreeS/WAN takes the position that systematically - eliminating this possibility at a low level is strongly preferable to - forcing careful consideration of possible impacts at every step of an - exchange. RFC 2408 [ISAKMP] section 3.1 states that the Message ID - of an ISAKMP message must be "unique". FreeS/WAN interprets this - literally, as forbidding duplication of Message IDs within the set of - - - -Spencer & Redelmeier [Page 6] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - all messages sent via a single ISAKMP SA. - - This requires remembering all Message IDs until the ISAKMP SA is - superseded by rekeying, but that is not costly (four bytes per sent - or received message), and it ELIMINATES replay attacks from - consideration; we believe this investment of resources is well - worthwhile. If the resource consumption becomes excessive--in our - experience it has not--the ISAKMP SA can be rekeyed early to collect - the garbage. - - There is theoretically an interoperability problem when talking to - implementations which interpret "unique" more loosely and may re-use - Message IDs, but it has not been encountered in practice. This - approach appears to be completely interoperable. - - The proposal by Andrew Krywaniuk [REPLAY], which advocates turning - the Message ID into an anti-replay counter, would achieve the same - goal without the minor per-message memory overhead. This may be - preferable, although it means an actual protocol change and more - study is needed. - -4. Basic Keying and Rekeying - -4.1. When to Create SAs - - As Tim Jenkins [REKEY] pointed out, there is a potential race - condition in Quick Mode: a fast lightly-loaded Initiator might start - using IPsec SAs very shortly after sending QM3 (the third and last - message of Quick Mode), while a slow heavily-loaded Responder might - not be ready to receive them until after spending a significant - amount of time creating its inbound SAs. The problem is even worse - if QM3 gets delayed or lost. - - FreeS/WAN's approach to this is what Jenkins called "Responder Pre- - Setup": the Responder creates its inbound IPsec SAs before it sends - QM2, so they are always ready and waiting when the Initiator sends - QM3 and begins sending traffic. This approach is simple and - reliable, and in our experience it interoperates with everybody. - (There is potentially still a problem if FreeS/WAN is the Initiator - and the Responder does not use Responder Pre-Setup, but no such - problems have been seen.) The only real weakness of Responder Pre- - Setup is the possibility of replay attacks, which we have eliminated - by other means (see section 3.3). - - With this approach, the Commit Bit is useless, and we ignore it. In - fact, until quite recently we discarded any IKE message containing - it, and this caused surprisingly few interoperability problems; - apparently it is not widely used. We have recently been persuaded - - - -Spencer & Redelmeier [Page 7] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - that simply ignoring it is preferable; preliminary experience with - this indicates that the result is successful interoperation with - implementations which set it. - -4.2. When to Rekey - - To preserve connectivity for user traffic, rekeying of a connection - (that is, creation of new IPsec SAs to supersede the current ones) - must begin before its current IPsec SAs expire. Preferably one end - should predictably start rekeying negotiations first, to avoid the - extra overhead of two simultaneous negotiations, although either end - should be prepared to rekey if the other does not. There is also a - problem with "convoys" of keying negotiations: for example, a "hub" - gateway with many IPsec connections can be inundated with rekeying - negotiations exactly one connection-expiry time after it reboots, and - the massive overload this induces tends to make this situation self- - perpetuating, so it recurs regularly. (Convoys can also evolve - gradually from initially-unsynchronized negotiations.) - - FreeS/WAN has the concept of a "rekeying margin", measured in - seconds. If FreeS/WAN was the Initiator for the previous rekeying - (or the startup, if none) of the connection, it nominally starts - rekeying negotiations at expiry time minus one rekeying margin. Some - random jitter is added to break up convoys: rather than starting - rekeying exactly at minus one margin, it starts at a random time - between minus one margin and minus two margins. (The randomness here - need not be cryptographic in quality, so long as it varies over time - and between hosts. We use an ordinary PRNG seeded with a few bytes - from a cryptographic randomness source. The seeding mostly just - ensures that the PRNG sequence is different for different hosts, even - if they start up simultaneously.) - - If FreeS/WAN was the Responder for the previous rekeying/startup, and - nothing has been heard from the previous Initiator at expiry time - minus one-half the rekeying margin, FreeS/WAN will initiate rekeying - negotiations. No jitter is applied; we now believe that it should be - jittered, say between minus one-half margin and minus one-quarter - margin. - - Having the Initiator lead the way is an obvious way of deciding who - should speak first, since there is already an Initiator/Responder - asymmetry in the connection. Moreover, our experience has been that - Initiator lead gives a significantly higher probability of successful - negotiation! The negotiation process itself is asymmetric, because - the Initiator must make a few specific proposals which the Responder - can only accept or reject, so the Initiator must try to guess where - its "acceptable" region (in parameter space) might overlap with the - Responder's. We have seen situations where negotiations would - - - -Spencer & Redelmeier [Page 8] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - succeed or fail depending on which end initiated them, because one - end was making better guesses. Given an existing connection, we KNOW - that the previous Initiator WAS able to initiate a successful - negotiation, so it should (if at all possible) take the lead again. - Also, the Responder should remember the Initiator's successful - proposal, and start from that rather than from his own default - proposals if he must take the lead; we don't currently implement this - completely but plan to. - - FreeS/WAN defaults the rekeying margin to 9 minutes, although this - can be changed by configuration. There is also a configuration - option to alter the permissible range of jitter. The defaults were - chosen somewhat arbitrarily, but they work extremely well and the - configuration options are rarely used. - -4.3. Choosing an SA - - Once rekeying has occurred, both old and new IPsec SAs for the - connection exist, at least momentarily. FreeS/WAN accepts incoming - traffic on either old or new inbound SAs, but sends outgoing traffic - only on the new outbound ones. This approach appears to be - significantly more robust than using the old ones until they expire, - notably in cases where renegotiation has occurred because something - has gone wrong on the other end. It avoids having to pay meticulous - attention to the state of the other end, state which is difficult to - learn reliably given the limitations of IKE. - - This approach has interoperated successfully with ALMOST all other - implementations. The only (well-characterized) problem cases have - been implementations which rely on receiving a Delete message for the - old SAs to tell them to switch over to the new ones. Since delivery - of Delete is unreliable, and support for Delete is optional, this - reliance seems like a serious mistake. This is all the more true - because Delete announces that the deletion has already occurred - [ISAKMP, section 3.15], not that it is about to occur, so packets - already in transit in the other direction could be lost. Delete - should be used for resource cleanup, not for switchover control. - (These matters are discussed further in section 5.) - -4.4. Why to Rekey - - FreeS/WAN currently implements only time-based expiry (life in - seconds), although we are working toward supporting volume-based - expiry (life in kilobytes) as well. The lack of volume-based expiry - has not been an interoperability problem so far. - - Volume-based expiry does add some minor complications. In - particular, it makes explicit Delete of now-disused SAs more - - - -Spencer & Redelmeier [Page 9] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - important, because once an SA stops being used, it might not expire - on its own. We believe this lacks robustness and is generally - unwise, especially given the lack of a reliable Delete, and expect to - use volume-based expiry only as a supplement to time-based expiry. - However, Delete support (see section 5) does seem advisable for use - with volume-based expiry. - - We do not believe that volume-based expiry alters the desirability of - switching immediately to the new SAs after rekeying. Rekeying - margins are normally a small fraction of the total life of an SA, so - we feel there is no great need to "use it all up". - -4.5. Rekeying ISAKMP SAs - - The above discussion has focused on rekeying for IPsec SAs, but - FreeS/WAN applies the same approaches to rekeying for ISAKMP SAs, - with similar success. - - One issue which we have noticed, but not explicitly dealt with, is - that difficulties may ensue if an IPsec-SA rekeying negotiation is in - progress at the time when the relevant ISAKMP SA gets rekeyed. The - IKE specification [IKE] hints, but does not actually say, that a - Quick Mode negotiation should remain on a single ISAKMP SA - throughout. - - A reasonable rekeying margin will generally prevent the old ISAKMP SA - from actually expiring during a negotiation. Some attention may be - needed to prevent in-progress negotiations from being switched to the - new ISAKMP SA. Any attempt at pre-expiry deletion of the ISAKMP SA - must be postponed until after such dangling negotiations are - completed, and there should be enough delay between ISAKMP-SA - rekeying and a deletion attempt to (more or less) ensure that there - are no negotiation-starting packets still in transit from before the - rekeying. - - At present, FreeS/WAN does none of this, and we don't KNOW of any - resulting trouble. With normal lifetimes, the problem should be - uncommon, and we speculate that an occasional disrupted negotiation - simply gets retried. - -4.6. Bulk Negotiation - - Quick Mode nominally provides for negotiating possibly-large numbers - of similar but unrelated IPsec SAs simultaneously [IKE, section 9]. - Nobody appears to do this. FreeS/WAN does not support it, and its - absence has caused no problems. - - - - - -Spencer & Redelmeier [Page 10] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - -5. Deletions, Teardowns, Crashes - - FreeS/WAN currently ignores all Notifications and Deletes, and never - generates them. This has caused little difficulty in - interoperability, which shouldn't be surprising (since Notification - and Delete support is officially entirely optional) but does seem to - surprise some people. Nevertheless, we do plan some changes to this - approach based on past experience. - -5.1. Deletions - - As hinted at above, we plan to implement Delete support, done as - follows. Shortly after rekeying of IPsec SAs, the Responder issues a - Delete for its old inbound SAs (but does not actually delete them - yet). The Responder initiates this because the Initiator started - using the new SAs on sending QM3, while the Responder started using - them only on (or somewhat after) receiving QM3, so there is less - chance of old-SA packets still being in transit from the Initiator. - The Initiator issues an unsolicited Delete only if it does not hear - one from the Responder after a longer delay. - - Either party, on receiving a Delete for one or more of the old - outbound SAs of a connection, deletes ALL the connection's SAs, and - acknowledges with a Delete for the old inbound SAs. A Delete for - nonexistent SAs (e.g., SAs which have already been expired or - deleted) is ignored. There is no retransmission of unacknowledged - Deletes. - - In the normal case, with prompt reliable transmission (except - possibly for loss of the Responder's initial Delete) and conforming - implementations on both ends, this results in three Deletes being - transmitted, resembling the classic three-way handshake. Loss of a - Delete after the first, or multiple losses, will cause the SAs not to - be deleted on at least one end. It appears difficult to do much - better without at least a distinction between request and - acknowledgement. - - RFC 2409 section 9 "strongly suggests" that there be no response to - informational messages such as Deletes, but the only rationale - offered is prevention of infinite loops endlessly exchanging "I don't - understand you" informationals. Since Deletes cannot lead to such a - loop (and in any case, the nonexistent-SA rule prevents more than one - acknowledgement for the same connection), we believe this - recommendation is inapplicable here. - - As noted in section 4.3, these Deletes are intended for resource - cleanup, not to control switching between SAs. But we expect that - they will improve interoperability with some broken implementations. - - - -Spencer & Redelmeier [Page 11] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - We believe strongly that connections need to be considered as a - whole, rather than treating each SA as an independent entity. We - will issue Deletes only for the full set of inbound SAs of a - connection, and will treat a Delete for any outbound SA as equivalent - to deletion of all the outbound SAs for the associated connection. - - The above is phrased in terms of IPsec SAs, but essentially the same - approach can be applied to ISAKMP SAs (the Deletes for the old ISAKMP - SA should be sent via the new one). - -5.2. Teardowns and Shutdowns - - When a connection is not intended to be up permanently, there is a - need to coordinate teardown, so that both ends are aware that the - connection is down. This is both for recovery of resources, and to - avoid routing packets through dangling SAs which can no longer - deliver them. - - Connection teardown will use the same bidirectional exchange of - Deletes as discussed in section 5.1: a Delete received for current - IPsec SAs (not yet obsoleted by rekeying) indicates that the other - host wishes to tear down the associated connection. - - A Delete received for a current ISAKMP SA indicates that the other - host wishes to tear down not only the ISAKMP SA but also all IPsec - SAs currently under the supervision of that ISAKMP SA. The 5.1 - bidirectional exchange might seem impossible in this case, since - reception of an ISAKMP-SA Delete indicates that the other end will - ignore further traffic on that ISAKMP SA. We suggest using the same - tactic discussed in 5.1 for IPsec SAs: the first Delete is sent - without actually doing the deletion, and the response to receiving a - Delete is to do the deletion and reply with another Delete. If there - is no response to the first Delete, retry a small number of times and - then give up and do the deletion; apart from being robust against - packet loss, this also maximizes the probability that an - implementation which does not do the bidirectional Delete will - receive at least one of the Deletes. - - When a host with current connections knows that it is about to shut - down, it will issue Deletes for all SAs involved (both IPsec and - ISAKMP), advising its peers (as per the meaning of Delete [ISAKMP, - section 3.15]) that the SAs have become useless. It will ignore - attempts at rekeying or connection startup thereafter, until it shuts - down. - - It would be better to have a Final-Contact notification, analogous to - Initial-Contact but indicating that no new negotiations should be - attempted until further notice. Initial-Contact actually could be - - - -Spencer & Redelmeier [Page 12] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - used for shutdown notification (!), but in networks where connections - are intended to exist permanently, it seems likely to provoke - unwanted attempts to renegotiate the lost connections. - -5.3. Crashes - - Systems sometimes crash. Coping with the resulting loss of - information is easily the most difficult problem we have found in - implementing robust IPsec systems. - - When connections are intended to be permanent, it is simple to - specify renegotiation on reboot. With our approach to SA selection - (see section 4.3), this handles such cases robustly and well. We do - have to tell users that BOTH hosts should be set this way. In cases - where crashes are synchronized (e.g. by power interruptions), this - may result in simultaneous negotiations at reboot. We currently - allow both negotiations to proceed to completion, but our use-newest - selection method effectively ignores one connection or the other, and - when one of them rekeys, we notice that the new SAs replace those of - both old connections, and we then refrain from rekeying the other. - (This duplicate detection is desirable in any event, for robustness, - to ensure that the system converges on a reasonable state eventually - after it is perturbed by difficulties or bugs.) - - When connections are not permanent, the situation is less happy. One - particular situation in which we see problems is when a number of - "Road Warrior" hosts occasionally call in to a central server. The - server is normally configured not to initiate such connections, since - it does not know when the Road Warrior is available (or what IP - address it is using). Unfortunately, if the server crashes and - reboots, any Road Warriors then connected have a problem: they don't - know that the server has crashed, so they can't renegotiate, and the - server has forgotten both the connections and their (transient) IP - addresses, so it cannot renegotiate. - - We believe that the simplest answer to this problem is what John - Denker has dubbed "address inertia": the server makes a best-effort - attempt to remember (in nonvolatile storage) which connections were - active and what the far-end addresses were (and what the successful - proposal's parameters were), so that it can attempt renegotiation on - reboot. We have not implemented this yet, but intend to; Denker has - implemented it himself, although in a somewhat messy way, and reports - excellent results. - -5.4. Network Partitions - - A network partition, making the two ends unable to reach each other, - has many of the same characteristics as having the other end crash... - - - -Spencer & Redelmeier [Page 13] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - until the network reconnects. It is desirable that recovery from - this be automatic. - - If the network reconnects before any rekeying attempts or other IKE - activities occurred, recovery is fully transparent, because the IKEs - have no idea that there was any problem. (Complaints such as ICMP - Host Unreachable messages are unauthenticated and hence cannot be - given much weight.) This fits the general mold of TCP/IP: if nobody - wanted to send any traffic, a network outage doesn't matter. - - If IKE activity did occur, the IKE implementation will discover that - the other end doesn't seem to be responding. The preferred response - to this depends on the nature of the connection. If it was intended - to be ephemeral (e.g. opportunistic encryption [OE]), closing it down - after a few retries is reasonable. If the other end is expected to - sometimes drop the connection without warning, it may not be - desirable to retry at all. (We support both these forms of - configurability, and indeed we also have a configuration option to - suppress rekeying entirely on one end.) - - If the connection was intended to be permanent, however, then - persistent attempts to re-establish it are appropriate. Some degree - of backoff is appropriate here, so that retries get less frequent as - the outage gets prolonged. Backoff should be limited, so that re- - established connectivity is not followed by a long delay before a - retry. Finally, after many retries (say 24 hours' worth), it may be - preferable to just declare the connection down and rely on manual - intervention to re-establish it, should this be desirable. We do not - yet fully support all this. - -5.5. Unknown SAs - - A more complete solution to crashes would be for an IPsec host to - note the arrival of ESP packets on an unknown IPsec SA, and report it - somehow to the other host, which can then decide to renegotiate. - This arguably might be preferable in any case--if the non-rebooted - host has no traffic to send, it does not care whether the connection - is intact--but delays and packet loss will be reduced if the - connection is renegotiated BEFORE there is traffic for it. So - unknown-SA detection is best reserved as a fallback method, with - address inertia used to deal with most such cases. - - A difficulty with unknown-SA detection is, just HOW should the other - host be notified? IKE provides no good way to do the notification: - Notification payloads (e.g., Initial-Contact) are unauthenticated - unless they are sent under protection of an ISAKMP SA. A "Security - Failures - Bad SPI" ICMP message [SECFAIL] is an interesting - alternative, but has the disadvantage of likewise being - - - -Spencer & Redelmeier [Page 14] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - unauthenticated. It's fundamentally unlikely that there is a simple - solution to this, given that almost any way of arranging or checking - authentication for such a notification is costly. - - We think the best answer to this is a two-step approach. An - unauthenticated Initial-Contact or Security Failures - Bad SPI cannot - be taken as a reliable report of a problem, but can be taken as a - hint that a problem MIGHT exist. Then there needs to be some - reliable way of checking such hints, subject to rate limiting since - the checks are likely to be costly (and checking the same connection - repeatedly at short intervals is unlikely to be worthwhile anyway). - So the rebooted host sends the notification, and the non-rebooted - host--which still thinks it has a connection--checks whether the - connection still works, and renegotiates if not. - - Also, if an IPsec host which believes it has a connection to another - host sees an unsuccessful attempt by that host to negotiate a new - one, that is also a hint of possible problems, justifying a check and - possible renegotiation. ("Unsuccessful" here means a negotiation - failure due to lack of a satisfactory proposal. A failure due to - authentication failure suggests a denial-of-service attack by a third - party, rather than a genuine problem on the legitimate other end.) - As noted in section 4.2, it is possible for negotiations to succeed - or fail based on which end initiates them, and some robustness - against that is desirable. - - We have not yet decided what form the notification should take. IKE - Initial-Contact is an obvious possibility, but has some - disadvantages. It does not specify which connection has had - difficulties. Also, the specification [IKE section 4.6.3.3] refers - to "remote system" and "sending system" without clearly specifying - just what "system" means; in the case of a multi-homed host using - multiple forms of identification, the question is not trivial. - Initial-Contact does have the fairly-decisive advantage that it is - likely to convey the right general meaning even to an implementation - which does not do things exactly the way ours does. - - A more fundamental difficulty is what form the reliable check takes. - What is wanted is an "IKE ping", verifying that the ISAKMP SA is - still intact (it being unlikely that IPsec SAs have been lost while - the ISAKMP SA has not). The lack of such a facility is a serious - failing of IKE. An acknowledged Notification of some sort would be - ideal, but there is none at present. Some existing implementations - are known to use the private Notification values 30000 as ping and - 30002 as ping reply, and that seems the most attractive choice at - present. If it is not recognized, there will probably be no reply, - and the result will be an unnecessary renegotiation, so this needs - strict rate limiting. (Also, when a new connection is set up, it's - - - -Spencer & Redelmeier [Page 15] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - probably worth determining by experiment whether the other end - supports IKE ping, and remembering that.) - - While we think this facility is desirable, and is about the best that - can be done with the poor tools available, we have not gotten very - far in implementation and cannot comment intelligently about how well - it works or interoperates. - -6. Misc. IKE Issues - -6.1. Groups 1 and 5 - - We have dropped support for the first Oakley Group (group 1), despite - it being officially mandatory, on the grounds that it is grossly too - weak to provide enough randomness for 3DES. There have been some - interoperability problems, mostly quite minor: ALMOST everyone - supports group 2 as well, although sometimes it has to be explicitly - configured. - - We also support the quasi-standard group 5 [GROUPS]. This has not - been seriously exercised yet, because historically we offered group 2 - first and almost everyone accepted it. We have recently changed to - offering group 5 first, and no difficulties have been reported. - -6.2. To PFS Or Not To PFS - - A persistent small interoperability problem is that the presence or - absence of PFS (for keys [IKE, section 5.5]) is neither negotiated - nor announced. We have it enabled by default, and successful - interoperation often requires having the other end turn it on in - their implementation, or having the FreeS/WAN end disable it. Almost - everyone supports it, but it's usually not the default, and - interoperability is often impossible unless the two ends somehow - reach prior agreement on it. - - We do not explicitly support the other flavor of PFS, for identities - [IKE, section 8], and this has caused no interoperability problems. - -6.3. Debugging Tools, Lack Thereof - - We find IKE lacking in basic debugging tools. Section 5.4, above, - notes that an IKE ping would be useful for connectivity verification. - It would also be extremely helpful for determining that UDP/500 - packets get back and forth successfully between the two ends, which - is often an important first step in debugging. - - It's also quite common to have IKE negotiate a connection - successfully, but to have some firewall along the way blocking ESP. - - - -Spencer & Redelmeier [Page 16] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - Users find this mysterious and difficult to diagnose. We have no - immediate suggestions on what could be done about it. - -6.4. Terminology, Vagueness Thereof - - The terminology of IPsec needs work. We feel that both the - specifications and user-oriented documentation would be greatly - clarified by concise, intelligible names for certain concepts. - - We semi-consistently use "group" for the set of IPsec SAs which are - established in one direction by a single Quick Mode negotiation and - are used together to process a packet (e.g., an ESP SA plus an AH - SA), "connection" for the logical packet path provided by a - succession of pairs of groups (each rekeying providing a new pair, - one group in each direction), and "keying channel" for the - corresponding supervisory path provided by a sequence of ISAKMP SAs. - - We think it's a botch that "PFS" is used to refer to two very - different things, but we have no specific new terms to suggest, since - we only implement one kind of PFS and thus can just ignore the other. - -6.5. A Question of Identity - - One specification problem deserves note: exactly when can an existing - phase 1 negotiation be re-used for a new phase 2 negotiation, as IKE - [IKE, section 4] specifies? Presumably, when it connects the same - two "parties"... but exactly what is a "party"? - - As noted in section 5.4, in cases involving multi-homing and multiple - identities, it's not clear exactly what criteria are used for - deciding whether the intended far end for a new negotiation is the - same one as for a previous negotiation. Is it by Identification - Payload? By IP address? Or what? - - We currently use a somewhat-vague notion of "identity", basically - what gets sent in Identification Payloads, for this, and this seems - to be successful, but we think this needs better specification. - -6.6. Opportunistic Encryption - - Further IKE challenges appear in the context of Opportunistic - Encryption [OE], but operational experience with it is too limited as - yet for us to comment usefully right now. - -6.7. Authentication and RSA Keys - - We provide two IKE authentication methods: shared secrets ("pre- - shared keys") and RSA digital signatures. (A user-provided add-on - - - -Spencer & Redelmeier [Page 17] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - package generalizes the latter to limited support for certificates; - we have not worked extensively with it ourselves yet and cannot - comment on it yet.) - - Shared secrets, despite their administrative difficulties, see - considerable use, and are also the method of last resort for - interoperability problems. - - For digital signatures, we have taken the somewhat unorthodox - approach of using "bare" RSA public keys, either supplied in - configuration files or fetched from DNS, rather than getting involved - in the complexity of certificates. We encode our RSA public keys - using the DNS KEY encoding [DNSRSA] (aka "RFC 2537", although that - RFC is now outdated), which has given us no difficulties and which we - highly recommend. We have seen two difficulties in connection with - RSA keys, however. - - First, while a number of IPsec implementations are able to take - "bare" RSA public keys, each one seems to have its own idea of what - format should be used for transporting them. We've had little - success with interoperability here, mostly because of key-format - issues; the implementations generally WILL interoperate successfully - if you can somehow get an RSA key into them at all, but that's hard. - X.509 certificates seem to be the lowest (!) common denominator for - key transfer. - - Second, although the content of RSA public keys has been stable, - there has been a small but subtle change over time in the content of - RSA private keys. The "internal modulus", used to compute the - private exponent "d" from the public exponent "e" (or vice-versa) was - originally [RSA] [PKCS1v1] [SCHNEIER] specified to be (p-1)*(q-1), - where p and q are the two primes. However, more recent definitions - [PKCS1v2] call it "lambda(n)" and define it to be lcm(p-1, q-1); this - appears to be a minor optimization. The result is that private keys - generated with the new definition often fail consistency checks in - implementations using the old definition. Fortunately, it is seldom - necessary to move private keys around. Our software now consistently - uses the new definition (and thus will accept keys generated with - either definition), but our key generator also has an option to - generate old-definition keys, for the benefit of users who upgrade - their networks incrementally. - -6.8. Misc. Snags - - Nonce size is another characteristic that is neither negotiated nor - announced but that the two ends must somehow be able to agree on. - Our software accepts anything between 8 and 256, and defaults to 16. - These numbers were chosen rather arbitrarily, but we have seen no - - - -Spencer & Redelmeier [Page 18] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - interoperability failures here. - - Nothing in the ISAKMP [ISAKMP] or IKE [IKE] specifications says - explicitly that a normal Message ID must be non-zero, but a zero - Message ID in fact causes failures. - - Similarly, there is nothing in the specs which says that ISAKMP - cookies must be non-zero, but zero cookies will in fact cause - trouble. - -7. Security Considerations - - Since this document discusses aspects of building robust and - interoperable IPsec implementations, security considerations permeate - it. - -8. References - - [AH] Kent, S., and Atkinson, R., "IP Authentication Header", - RFC 2402, Nov 1998. - - [CIPHERS] Pereira, R., and Adams, R., "The ESP CBC-Mode Cipher - Algorithms", RFC 2451, Nov 1998. - - [CRACK] Electronic Frontier Foundation, "Cracking DES: Secrets of - Encryption Research, Wiretap Politics and Chip Design", - O'Reilly 1998, ISBN 1-56592-520-3. - - [DES] Madson, C., and Doraswamy, N., "The ESP DES-CBC Cipher - Algorithm", RFC 2405, Nov 1998. - - [DNSRSA] D. Eastlake 3rd, "RSA/SHA-1 SIGs and RSA KEYs in the - Domain Name System (DNS)", RFC 3110, May 2001. - - [ESP] Kent, S., and Atkinson, R., "IP Encapsulating Security - Payload (ESP)", RFC 2406, Nov 1998. - - [GROUPS] Kivinen, T., and Kojo, M., "More MODP Diffie-Hellman - groups for IKE", , 13 Dec 2001 (work in progress). - - [IKE] Harkins, D., and Carrel, D., "The Internet Key Exchange - (IKE)", RFC 2409, Nov 1998. - - [IPSEC] Kent, S., and Atkinson, R., "Security Architecture for the - Internet Protocol", RFC 2401, Nov 1998. - - - - - -Spencer & Redelmeier [Page 19] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - [ISAKMP] Maughan, D., Schertler, M., Schneider, M., and Turner, J., - "Internet Security Association and Key Management Protocol - (ISAKMP)", RFC 2408, Nov 1998. - - [OE] Richardson, M., Redelmeier, D. H., and Spencer, H., "A - method for doing opportunistic encryption with IKE", - , 21 Feb 2002 - (work in progress). - - [PKCS1v1] Kaliski, B., "PKCS #1: RSA Encryption, Version 1.5", RFC - 2313, March 1998. - - [PKCS1v2] Kaliski, B., and Staddon, J., "PKCS #1: RSA Cryptography - Specifications, Version 2.0", RFC 2437, Oct 1998. - - [PFKEY] McDonald, D., Metz, C., and Phan, B., "PF_KEY Key - Management API, Version 2", RFC 2367, July 1998. - - [REKEY] Tim Jenkins, "IPsec Re-keying Issues", , 2 May 2000 (draft expired, work no - longer in progress). - - [REPLAY] Krywaniuk, A., "Using Isakmp Message Ids for Replay - Protection", , 9 - July 2001 (work in progress). - - [RSA] Rivest, R.L., Shamir, A., and Adleman, L., "A Method for - Obtaining Digital Signatures and Public-Key - Cryptosystems", Communications of the ACM v21n2, Feb 1978, - p. 120. - - [SCHNEIER] Bruce Schneier, "Applied Cryptography", 2nd ed., Wiley - 1996, ISBN 0-471-11709-9. - - [SECFAIL] Karn, P., and Simpson, W., "ICMP Security Failures - Messages", RFC 2521, March 1999. - -Authors' Addresses - - Henry Spencer - SP Systems - Box 280 Stn. A - Toronto, Ont. M5W1B2 - Canada - - henry@spsystems.net - 416-690-6561 - - - - -Spencer & Redelmeier [Page 20] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - - D. Hugh Redelmeier - Mimosa Systems Inc. - 29 Donino Ave. - Toronto, Ont. M4N2W6 - Canada - - hugh@mimosa.com - 416-482-8253 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Spencer & Redelmeier [Page 21] - -Internet Draft IKE Implementation Issues 26 Feb 2002 - - -Full Copyright Statement - - Copyright (C) The Internet Society 2002. All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implmentation may be prepared, copied, published and - distributed, in whole or in part, without restriction of any kind, - provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Spencer & Redelmeier [Page 22] - diff --git a/doc/manpage.d/ipsec.8.html b/doc/manpage.d/ipsec.8.html deleted file mode 100644 index ff9b7ca39..000000000 --- a/doc/manpage.d/ipsec.8.html +++ /dev/null @@ -1,215 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC - -

IPSEC

-Section: Maintenance Commands (8)
Updated: 26 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec - invoke IPsec utilities -  -

SYNOPSIS

- -ipsec - -command [ argument ...] -

-ipsec - ---help - -
- -ipsec - ---version - -
- -ipsec - ---versioncode - -
- -ipsec - ---copyright - -
- -ipsec - ---directory - -
- -ipsec - ---confdir - -  -

DESCRIPTION

- -Ipsec - -invokes any of several utilities involved in controlling the IPsec -encryption/authentication system, -running the specified -command - -with the specified -arguments - -as if it had been invoked directly. -This largely eliminates possible name collisions with other software, -and also permits some centralized services. -

- -In particular, -ipsec - -supplies the invoked -command - -with a suitable PATH environment variable, -and also provides IPSEC_DIR, -IPSEC_CONFS, and IPSEC_VERSION environment variables, -containing respectively -the full pathname of the directory where the IPsec utilities are stored, -the full pathname of the directory where the configuration files live, -and the IPsec version number. -

- -ipsec --help - -lists the available commands. -Most have their own manual pages, e.g. -ipsec_auto(8) - -for -auto. - -

- -ipsec --version - -outputs version information about Linux FreeS/WAN. -A version code of the form ``Uxxx/Kyyy'' -indicates that the user-level utilities are version xxx -but the kernel portion appears to be version yyy -(this form is used only if the two disagree). -

- -ipsec --versioncode - -outputs just the version code, -with none of ---version's - -supporting information, -for use by scripts. -

- -ipsec --copyright - -supplies boring copyright details. -

- -ipsec --directory - -reports where -ipsec - -thinks the IPsec utilities are stored. -

- -ipsec --confdir - -reports where -ipsec - -thinks the IPsec configuration files are stored. -  -

FILES

- -/usr/local/lib/ipsec   usual utilities directory
-  -

ENVIRONMENT

- -

- -The following environment variables control where FreeS/WAN finds its -components. -The -ipsec - -command sets them if they are not already set. -

-IPSEC_EXECDIR   directory containing published commands
-IPSEC_LIBDIR    directory containing internal executables
-IPSEC_SBINDIR   directory containing ipsec command
-IPSEC_CONFS     directory containing configuration files
-
- -  -

SEE ALSO

- - - -ipsec.conf(5), ipsec.secrets(5), -ipsec_auto(8), -ipsec_barf(8), -ipsec_setup(8), -ipsec_showdefaults(8), -ipsec_showhostkey(8) - - -

- -HTML documentation shipped with the release, starting with -doc/index.html. - -<http://www.freeswan.org/doc.html> - -may also be of use. -  -

HISTORY

- -Written for Linux FreeS/WAN -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -The provision of centralized services, -while convenient, -does compromise the original concept of making the utilities -invocable directly as well as via -ipsec. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
ENVIRONMENT
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec.conf.5.html b/doc/manpage.d/ipsec.conf.5.html deleted file mode 100644 index 36e0452ef..000000000 --- a/doc/manpage.d/ipsec.conf.5.html +++ /dev/null @@ -1,1830 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC.CONF - -

IPSEC.CONF

-Section: File Formats (5)
Updated: 26 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec.conf - IPsec configuration and connections -  -

DESCRIPTION

- -The optional -ipsec.conf - -file -specifies most configuration and control information for the -FreeS/WAN IPsec subsystem. -(The major exception is secrets for authentication; -see -ipsec.secrets(5).) - -Its contents are not security-sensitive -unless - -manual keying is being done for more than just testing, -in which case the encryption/authentication keys in the -descriptions for the manually-keyed connections are very sensitive -(and those connection descriptions -are probably best kept in a separate file, -via the include facility described below). -

- -The file is a text file, consisting of one or more -sections. - -White space followed by -# - -followed by anything to the end of the line -is a comment and is ignored, -as are empty lines which are not within a section. -

- -A line which contains -include - -and a file name, separated by white space, -is replaced by the contents of that file, -preceded and followed by empty lines. -If the file name is not a full pathname, -it is considered to be relative to the directory containing the -including file. -Such inclusions can be nested. -Only a single filename may be supplied, and it may not contain white space, -but it may include shell wildcards (see -sh(1)); - -for example: -

- -include - -ipsec.*.conf - -

- -The intention of the include facility is mostly to permit keeping -information on connections, or sets of connections, -separate from the main configuration file. -This permits such connection descriptions to be changed, -copied to the other security gateways involved, etc., -without having to constantly extract them from the configuration -file and then insert them back into it. -Note also the -also - -and -alsoflip - -parameters (described below) which permit splitting a single logical section -(e.g. a connection description) into several actual sections. -

- -The first significant line of the file must specify the version -of this specification that it conforms to: -

- -version 2 -

- -A section -begins with a line of the form: -

- -type - -name - -

- -where -type - -indicates what type of section follows, and -name - -is an arbitrary name which distinguishes the section from others -of the same type. -(Names must start with a letter and may contain only -letters, digits, periods, underscores, and hyphens.) -All subsequent non-empty lines -which begin with white space are part of the section; -comments within a section must begin with white space too. -There may be only one section of a given type with a given name. -

- -Lines within the section are generally of the form -

- -     parameter=value -

- -(note the mandatory preceding white space). -There can be white space on either side of the -=. - -Parameter names follow the same syntax as section names, -and are specific to a section type. -Unless otherwise explicitly specified, -no parameter name may appear more than once in a section. -

- -An empty -value - -stands for the system default value (if any) of the parameter, -i.e. it is roughly equivalent to omitting the parameter line entirely. -A -value - -may contain white space only if the entire -value - -is enclosed in double quotes ("); -a -value - -cannot itself contain a double quote, -nor may it be continued across more than one line. -

- -Numeric values are specified to be either an ``integer'' -(a sequence of digits) or a ``decimal number'' -(sequence of digits optionally followed by `.' and another sequence of digits). -

- -There is currently one parameter which is available in any type of -section: -

-
also - -
-the value is a section name; -the parameters of that section are appended to this section, -as if they had been written as part of it. -The specified section must exist, must follow the current one, -and must have the same section type. -(Nesting is permitted, -and there may be more than one -also - -in a single section, -although it is forbidden to append the same section more than once.) -This allows, for example, keeping the encryption keys -for a connection in a separate file -from the rest of the description, by using both an -also - -parameter and an -include - -line. -(Caution, see BUGS below for some restrictions.) -
alsoflip - -
-can be used in a -conn - -section. -It acts like an -also - -that flips the referenced section's entries left-for-right. -
-

- -Parameter names beginning with -x- - -(or -X-, - -or -x_, - -or -X_) - -are reserved for user extensions and will never be assigned meanings -by IPsec. -Parameters with such names must still observe the syntax rules -(limits on characters used in the name; -no white space in a non-quoted value; -no newlines or double quotes within the value). -All other as-yet-unused parameter names are reserved for future IPsec -improvements. -

- -A section with name -%default - -specifies defaults for sections of the same type. -For each parameter in it, -any section of that type which does not have a parameter of the same name -gets a copy of the one from the -%default - -section. -There may be multiple -%default - -sections of a given type, -but only one default may be supplied for any specific parameter name, -and all -%default - -sections of a given type must precede all non-%default - -sections of that type. -%default - -sections may not contain -also - -or -alsoflip - -parameters. -

- -Currently there are two types of section: -a -config - -section specifies general configuration information for IPsec, -while a -conn - -section specifies an IPsec connection. -  -

CONN SECTIONS

- -A -conn - -section contains a -connection specification, - -defining a network connection to be made using IPsec. -The name given is arbitrary, and is used to identify the connection to -ipsec_auto(8) - -and -ipsec_manual(8). - -Here's a simple example: -

- - -

-
-conn snt
- left=10.11.11.1
- leftsubnet=10.0.1.0/24
- leftnexthop=172.16.55.66
- right=192.168.22.1
- rightsubnet=10.0.2.0/24
- rightnexthop=172.16.88.99
- keyingtries=%forever
-
- -

- -A note on terminology... -In automatic keying, there are two kinds of communications going on: -transmission of user IP packets, and gateway-to-gateway negotiations for -keying, rekeying, and general control. -The data path (a set of ``IPsec SAs'') used for user packets is herein -referred to as the ``connection''; -the path used for negotiations (built with ``ISAKMP SAs'') is referred to as -the ``keying channel''. -

- -To avoid trivial editing of the configuration file to suit it to each system -involved in a connection, -connection specifications are written in terms of -left - -and -right - -participants, -rather than in terms of local and remote. -Which participant is considered -left - -or -right - -is arbitrary; -IPsec figures out which one it is being run on based on internal information. -This permits using identical connection specifications on both ends. -There are cases where there is no symmetry; a good convention is to -use -left - -for the local side and -right - -for the remote side (the first letters are a good mnemonic). -

- -Many of the parameters relate to one participant or the other; -only the ones for -left - -are listed here, but every parameter whose name begins with -left - -has a -right - -counterpart, -whose description is the same but with -left - -and -right - -reversed. -

- -Parameters are optional unless marked ``(required)''; -a parameter required for manual keying need not be included for -a connection which will use only automatic keying, and vice versa. -  -

CONN PARAMETERS: GENERAL

- -The following parameters are relevant to both automatic and manual keying. -Unless otherwise noted, -for a connection to work, -in general it is necessary for the two ends to agree exactly -on the values of these parameters. -
-
type - -
-the type of the connection; currently the accepted values -are -tunnel - -(the default) -signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; -transport, - -signifying host-to-host transport mode; -passthrough, - -signifying that no IPsec processing should be done at all; -drop, - -signifying that packets should be discarded; and -reject, - -signifying that packets should be discarded and a diagnostic ICMP returned. -
left - -
-(required) -the IP address of the left participant's public-network interface, -in any form accepted by -ipsec_ttoaddr(3) - -or one of several magic values. -If it is -%defaultroute, - -and -the -config - -setup - -section's, -interfaces - -specification contains -%defaultroute, - -left - -will be filled in automatically with the local address -of the default-route interface (as determined at IPsec startup time); -this also overrides any value supplied for -leftnexthop. - -(Either -left - -or -right - -may be -%defaultroute, - -but not both.) -The value -%any - -signifies an address to be filled in (by automatic keying) during -negotiation. -The value -%opportunistic - -signifies that both -left - -and -leftnexthop - -are to be filled in (by automatic keying) from DNS data for -left's - -client. -The values -%group - -and -%opportunisticgroup - -makes this a policy group conn: one that will be instantiated -into a regular or opportunistic conn for each CIDR block listed in the -policy group file with the same name as the conn. -
leftsubnet - -
-private subnet behind the left participant, expressed as -network/netmask -(actually, any form acceptable to -ipsec_ttosubnet(3)); - -if omitted, essentially assumed to be left/32, -signifying that the left end of the connection goes to the left participant only -
leftnexthop - -
-next-hop gateway IP address for the left participant's connection -to the public network; -defaults to -%direct - -(meaning -right). - -If the value is to be overridden by the -left=%defaultroute - -method (see above), -an explicit value must -not - -be given. -If that method is not being used, -but -leftnexthop - -is -%defaultroute, - -and -interfaces=%defaultroute - -is used in the -config - -setup - -section, -the next-hop gateway address of the default-route interface -will be used. -The magic value -%direct - -signifies a value to be filled in (by automatic keying) -with the peer's address. -Relevant only locally, other end need not agree on it. -
leftupdown - -
-what ``updown'' script to run to adjust routing and/or firewalling -when the status of the connection -changes (default -ipsec _updown). - -May include positional parameters separated by white space -(although this requires enclosing the whole string in quotes); -including shell metacharacters is unwise. -See -ipsec_pluto(8) - -for details. -Relevant only locally, other end need not agree on it. -
leftfirewall - -
-whether the left participant is doing forwarding-firewalling -(including masquerading) for traffic from leftsubnet, -which should be turned off (for traffic to the other subnet) -once the connection is established; -acceptable values are -yes - -and (the default) -no. - -May not be used in the same connection description with -leftupdown. - -Implemented as a parameter to the default -updown - -script. -See notes below. -Relevant only locally, other end need not agree on it. -
-

- -If one or both security gateways are doing forwarding firewalling -(possibly including masquerading), -and this is specified using the firewall parameters, -tunnels established with IPsec are exempted from it -so that packets can flow unchanged through the tunnels. -(This means that all subnets connected in this manner must have -distinct, non-overlapping subnet address blocks.) -This is done by the default -updown - -script (see -ipsec_pluto(8)). - -

- -The implementation of this makes certain assumptions about firewall setup, -notably the use of the old -ipfwadm - -interface to the firewall. -In situations calling for more control, -it may be preferable for the user to supply his own -updown - -script, -which makes the appropriate adjustments for his system. -  -

CONN PARAMETERS: AUTOMATIC KEYING

- -The following parameters are relevant only to automatic keying, -and are ignored in manual keying. -Unless otherwise noted, -for a connection to work, -in general it is necessary for the two ends to agree exactly -on the values of these parameters. -
-
keyexchange - -
-method of key exchange; -the default and currently the only accepted value is -ike - -
auto - -
-what operation, if any, should be done automatically at IPsec startup; -currently-accepted values are -add - -(signifying an -ipsec auto - ---add), - -route - -(signifying that plus an -ipsec auto - ---route), - -start - -(signifying that plus an -ipsec auto - ---up), - -manual - -(signifying an -ipsec - -manual - ---up), - -and -ignore - -(also the default) (signifying no automatic startup operation). -See the -config - -setup - -discussion below. -Relevant only locally, other end need not agree on it -(but in general, for an intended-to-be-permanent connection, -both ends should use -auto=start - -to ensure that any reboot causes immediate renegotiation). -
auth - -
-whether authentication should be done as part of -ESP encryption, or separately using the AH protocol; -acceptable values are -esp - -(the default) and -ah. - -
authby - -
-how the two security gateways should authenticate each other; -acceptable values are -secret - -for shared secrets, -rsasig - -for RSA digital signatures (the default), -secret|rsasig - -for either, and -never - -if negotiation is never to be attempted or accepted (useful for shunt-only conns). -Digital signatures are superior in every way to shared secrets. -
leftid - -
-how -the left participant -should be identified for authentication; -defaults to -left. - -Can be an IP address (in any -ipsec_ttoaddr(3) - -syntax) -or a fully-qualified domain name preceded by -@ - -(which is used as a literal string and not resolved). -The magic value -%myid - -stands for the current setting of myid. -This is set in config setup or by ipsec_whack(8)), or, if not set, -it is the IP address in %defaultroute (if that is supported by a TXT record in its reverse domain), or otherwise -it is the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined. -
leftrsasigkey - -
-the left participant's -public key for RSA signature authentication, -in RFC 2537 format using -ipsec_ttodata(3) - -encoding. -The magic value -%none - -means the same as not specifying a value (useful to override a default). -The value -%dnsondemand - -(the default) -means the key is to be fetched from DNS at the time it is needed. -The value -%dnsonload - -means the key is to be fetched from DNS at the time -the connection description is read from -ipsec.conf; - -currently this will be treated as -%none - -if -right=%any - -or -right=%opportunistic. - -The value -%dns - -is currently treated as -%dnsonload - -but will change to -%dnsondemand - -in the future. -The identity used for the left participant -must be a specific host, not -%any - -or another magic value. -Caution: - -if two connection descriptions -specify different public keys for the same -leftid, - -confusion and madness will ensue. -
leftrsasigkey2 - -
-if present, a second public key. -Either key can authenticate the signature, allowing for key rollover. -
pfs - -
-whether Perfect Forward Secrecy of keys is desired on the connection's -keying channel -(with PFS, penetration of the key-exchange protocol -does not compromise keys negotiated earlier); -acceptable values are -yes - -(the default) -and -no. - -
keylife - -
-how long a particular instance of a connection -(a set of encryption/authentication keys for user packets) should last, -from successful negotiation to expiry; -acceptable values are an integer optionally followed by -s - -(a time in seconds) -or a decimal number followed by -m, - -h, - -or -d - -(a time -in minutes, hours, or days respectively) -(default -8.0h, - -maximum -24h). - -Normally, the connection is renegotiated (via the keying channel) -before it expires. -The two ends need not exactly agree on -keylife, - -although if they do not, -there will be some clutter of superseded connections on the end -which thinks the lifetime is longer. -
rekey - -
-whether a connection should be renegotiated when it is about to expire; -acceptable values are -yes - -(the default) -and -no. - -The two ends need not agree, -but while a value of -no - -prevents Pluto from requesting renegotiation, -it does not prevent responding to renegotiation requested from the other end, -so -no - -will be largely ineffective unless both ends agree on it. -
rekeymargin - -
-how long before connection expiry or keying-channel expiry -should attempts to -negotiate a replacement -begin; acceptable values as for -keylife - -(default -9m). - -Relevant only locally, other end need not agree on it. -
rekeyfuzz - -
-maximum percentage by which -rekeymargin - -should be randomly increased to randomize rekeying intervals -(important for hosts with many connections); -acceptable values are an integer, -which may exceed 100, -followed by a `%' -(default set by -ipsec_pluto(8), - -currently -100%). - -The value of -rekeymargin, - -after this random increase, -must not exceed -keylife. - -The value -0% - -will suppress time randomization. -Relevant only locally, other end need not agree on it. -
keyingtries - -
-how many attempts (a whole number or %forever) should be made to -negotiate a connection, or a replacement for one, before giving up -(default -%forever). - -The value %forever -means ``never give up'' (obsolete: this can be written 0). -Relevant only locally, other end need not agree on it. -
ikelifetime - -
-how long the keying channel of a connection (buzzphrase: ``ISAKMP SA'') -should last before being renegotiated; -acceptable values as for -keylife - -(default set by -ipsec_pluto(8), - -currently -1h, - -maximum -8h). - -The two-ends-disagree case is similar to that of -keylife. - -
compress - -
-whether IPComp compression of content is proposed on the connection -(link-level compression does not work on encrypted data, -so to be effective, compression must be done before encryption); -acceptable values are -yes - -and -no - -(the default). -The two ends need not agree. -A value of -yes - -causes IPsec to propose both compressed and uncompressed, -and prefer compressed. -A value of -no - -prevents IPsec from proposing compression; -a proposal to compress will still be accepted. -
disablearrivalcheck - -
-whether KLIPS's normal tunnel-exit check -(that a packet emerging from a tunnel has plausible addresses in its header) -should be disabled; -acceptable values are -yes - -and -no - -(the default). -Tunnel-exit checks improve security and do not break any normal configuration. -Relevant only locally, other end need not agree on it. -
failureshunt - -
-what to do with packets when negotiation fails. -The default is -none: - -no shunt; -passthrough, - -drop, - -and -reject - -have the obvious meanings. -
-  -

CONN PARAMETERS: MANUAL KEYING

- -The following parameters are relevant only to manual keying, -and are ignored in automatic keying. -Unless otherwise noted, -for a connection to work, -in general it is necessary for the two ends to agree exactly -on the values of these parameters. -A manually-keyed -connection must specify at least one of AH or ESP. -
-
spi - -
-(this or -spibase - -required for manual keying) -the SPI number to be used for the connection (see -ipsec_manual(8)); - -must be of the form 0xhex, -where -hex - -is one or more hexadecimal digits -(note, it will generally be necessary to make -spi - -at least -0x100 - -to be acceptable to KLIPS, -and use of SPIs in the range -0x100-0xfff - -is recommended) -
spibase - -
-(this or -spi - -required for manual keying) -the base number for the SPIs to be used for the connection (see -ipsec_manual(8)); - -must be of the form 0xhex0, -where -hex - -is one or more hexadecimal digits -(note, it will generally be necessary to make -spibase - -at least -0x100 - -for the resulting SPIs -to be acceptable to KLIPS, -and use of numbers in the range -0x100-0xff0 - -is recommended) -
esp - -
-ESP encryption/authentication algorithm to be used -for the connection, e.g. -3des-md5-96 - -(must be suitable as a value of -ipsec_spi(8)'s - ---esp - -option); -default is not to use ESP -
espenckey - -
-ESP encryption key -(must be suitable as a value of -ipsec_spi(8)'s - ---enckey - -option) -(may be specified separately for each direction using -leftespenckey - -(leftward SA) -and -rightespenckey - -parameters) -
espauthkey - -
-ESP authentication key -(must be suitable as a value of -ipsec_spi(8)'s - ---authkey - -option) -(may be specified separately for each direction using -leftespauthkey - -(leftward SA) -and -rightespauthkey - -parameters) -
espreplay_window - -
-ESP replay-window setting, -an integer from -0 - -(the -ipsec_manual - -default, which turns off replay protection) to -64; - -relevant only if ESP authentication is being used -
leftespspi - -
-SPI to be used for the leftward ESP SA, overriding -automatic assignment using -spi - -or -spibase; - -typically a hexadecimal number beginning with -0x - -
ah - -
-AH authentication algorithm to be used -for the connection, e.g. -hmac-md5-96 - -(must be suitable as a value of -ipsec_spi(8)'s - ---ah - -option); -default is not to use AH -
ahkey - -
-(required if -ah - -is present) AH authentication key -(must be suitable as a value of -ipsec_spi(8)'s - ---authkey - -option) -(may be specified separately for each direction using -leftahkey - -(leftward SA) -and -rightahkey - -parameters) -
ahreplay_window - -
-AH replay-window setting, -an integer from -0 - -(the -ipsec_manual - -default, which turns off replay protection) to -64 - -
leftahspi - -
-SPI to be used for the leftward AH SA, overriding -automatic assignment using -spi - -or -spibase; - -typically a hexadecimal number beginning with -0x - -
-  -

CONFIG SECTIONS

- -At present, the only -config - -section known to the IPsec software is the one named -setup, - -which contains information used when the software is being started -(see -ipsec_setup(8)). - -Here's an example: -

- - -

-
-config setup
- interfaces="ipsec0=eth1 ipsec1=ppp0"
- klipsdebug=none
- plutodebug=all
- manualstart=
-
- -

- -Parameters are optional unless marked ``(required)''. -The currently-accepted -parameter - -names in a -config - -setup - -section are: -

-
myid - -
-the identity to be used for -%myid. - -%myid - -is used in the implicit policy group conns and can be used as -an identity in explicit conns. -If unspecified, -%myid - -is set to the IP address in %defaultroute (if that is supported by a TXT record in its reverse domain), or otherwise -the system's hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined. -An explicit value generally starts with ``@''. -
interfaces - -
-virtual and physical interfaces for IPsec to use: -a single -virtual=physical pair, a (quoted!) list of pairs separated -by white space, or -%none. - -One of the pairs may be written as -%defaultroute, - -which means: find the interface d that the default route points to, -and then act as if the value was ``ipsec0=d''. -%defaultroute - -is the default; -%none - -must be used to denote no interfaces. -If -%defaultroute - -is used (implicitly or explicitly) -information about the default route and its interface is noted for -use by -ipsec_manual(8) - -and -ipsec_auto(8).) - -
forwardcontrol - -
-whether -setup - -should turn IP forwarding on -(if it's not already on) as IPsec is started, -and turn it off again (if it was off) as IPsec is stopped; -acceptable values are -yes - -and (the default) -no. - -For this to have full effect, forwarding must be -disabled before the hardware interfaces are brought -up (e.g., -net.ipv4.ip_forward = 0 - -in Red Hat 6.x -/etc/sysctl.conf), - -because IPsec doesn't get control early enough to do that. -
rp_filter - -
-whether and how -setup - -should adjust the reverse path filtering mechanism for the -physical devices to be used. -Values are %unchanged (to leave it alone) -or 0, 1, 2 (values to set it to). -/proc/sys/net/ipv4/conf/PHYS/rp_filter -is badly documented; it must be 0 in many cases -for ipsec to function. -The default value for the parameter is 0. -
syslog - -
-the -syslog(2) - -``facility'' name and priority to use for -startup/shutdown log messages, -default -daemon.error. - -
klipsdebug - -
-how much KLIPS debugging output should be logged. -An empty value, -or the magic value -none, - -means no debugging output (the default). -The magic value -all - -means full output. -Otherwise only the specified types of output -(a quoted list, names separated by white space) are enabled; -for details on available debugging types, see -ipsec_klipsdebug(8). - -
plutodebug - -
-how much Pluto debugging output should be logged. -An empty value, -or the magic value -none, - -means no debugging output (the default). -The magic value -all - -means full output. -Otherwise only the specified types of output -(a quoted list, names without the ---debug- - -prefix, -separated by white space) are enabled; -for details on available debugging types, see -ipsec_pluto(8). - -
plutoopts - -
-additional options to pass to pluto upon startup. See -ipsec_pluto(8). - -
plutostderrlog - -
-do not use syslog, but rather log to stderr, and direct stderr to the -argument file. -
dumpdir - -
-in what directory should things started by -setup - -(notably the Pluto daemon) be allowed to -dump core? -The empty value (the default) means they are not -allowed to. -
manualstart - -
-which manually-keyed connections to set up at startup -(empty, a name, or a quoted list of names separated by white space); -see -ipsec_manual(8). - -Default is none. -
pluto - -
-whether to start Pluto or not; -Values are -yes - -(the default) -or -no - -(useful only in special circumstances). -
plutowait - -
-should Pluto wait for each -negotiation attempt that is part of startup to -finish before proceeding with the next? -Values are -yes - -or -no - -(the default). -
prepluto - -
-shell command to run before starting Pluto -(e.g., to decrypt an encrypted copy of the -ipsec.secrets - -file). -It's run in a very simple way; -complexities like I/O redirection are best hidden within a script. -Any output is redirected for logging, -so running interactive commands is difficult unless they use -/dev/tty - -or equivalent for their interaction. -Default is none. -
postpluto - -
-shell command to run after starting Pluto -(e.g., to remove a decrypted copy of the -ipsec.secrets - -file). -It's run in a very simple way; -complexities like I/O redirection are best hidden within a script. -Any output is redirected for logging, -so running interactive commands is difficult unless they use -/dev/tty - -or equivalent for their interaction. -Default is none. -
fragicmp - -
-whether a tunnel's need to fragment a packet should be reported -back with an ICMP message, -in an attempt to make the sender lower his PMTU estimate; -acceptable values are -yes - -(the default) -and -no. - -
hidetos - -
-whether a tunnel packet's TOS field should be set to -0 - -rather than copied from the user packet inside; -acceptable values are -yes - -(the default) -and -no. - -
uniqueids - -
-whether a particular participant ID should be kept unique, -with any new (automatically keyed) -connection using an ID from a different IP address -deemed to replace all old ones using that ID; -acceptable values are -yes - -(the default) -and -no. - -Participant IDs normally are unique, -so a new (automatically-keyed) connection using the same ID is -almost invariably intended to replace an old one. -
overridemtu - -
-value that the MTU of the ipsecn interface(s) should be set to, -overriding IPsec's (large) default. -This parameter is needed only in special situations. -
-  -

IMPLICIT CONNS

- -

- -The system automatically defines several conns to implement -default policy groups. Each can be overridden by explicitly -defining a new conn with the same name. If the new conn has auto=ignore, -the definition is suppressed. -

- -Here are the automatically supplied definitions. -

- - -

-
-conn clear
- type=passthrough
- authby=never
- left=%defaultroute
- right=%group
- auto=route
-
-conn clear-or-private
- type=passthrough
- left=%defaultroute
- leftid=%myid
- right=%opportunisticgroup
- failureshunt=passthrough
- keyingtries=3
- ikelifetime=1h
- keylife=1h
- rekey=no
- auto=route
-
-conn private-or-clear
- type=tunnel
- left=%defaultroute
- leftid=%myid
- right=%opportunisticgroup
- failureshunt=passthrough
- keyingtries=3
- ikelifetime=1h
- keylife=1h
- rekey=no
- auto=route
-
-conn private
- type=tunnel
- left=%defaultroute
- leftid=%myid
- right=%opportunisticgroup
- failureshunt=drop
- keyingtries=3
- ikelifetime=1h
- keylife=1h
- rekey=no
- auto=route
-
-conn block
- type=reject
- authby=never
- left=%defaultroute
- right=%group
- auto=route
-
-# default policy
-conn packetdefault
- type=tunnel
- left=%defaultroute
- leftid=%myid
- left=0.0.0.0/0
- right=%opportunistic
- failureshunt=passthrough
- keyingtries=3
- ikelifetime=1h
- keylife=1h
- rekey=no
- auto=route
-
- -

- -These conns are not affected by anything in conn %default. -They will only work if %defaultroute works. -The leftid will be the interfaces IP address; this -requires that reverse DNS records be set up properly. -

- -The implicit conns are defined after all others. It is -appropriate and reasonable to use also=private-or-clear -(for example) in any other opportunistic conn. -  -

POLICY GROUP FILES

- -

- -The optional files under -/etc/ipsec.d/policy, - -including -

-
-/etc/ipsec.d/policies/clear
-/etc/ipsec.d/policies/clear-or-private
-/etc/ipsec.d/policies/private-or-clear
-/etc/ipsec.d/policies/private
-/etc/ipsec.d/policies/block
-
-
- -may contain policy group configuration information to -supplement -ipsec.conf. - -Their contents are not security-sensitive. -

- -These files are text files. -Each consists of a list of CIDR blocks, one per line. -White space followed by # followed by anything to the end of the line -is a comment and is ignored, as are empty lines. -

- -A connection in -/etc/ipsec.conf - -which has -right=%group - -or -right=%opportunisticgroup - -is a policy group connection. -When a policy group file of the same name is loaded, with -

- -     ipsec auto --rereadgroups -

- -or at system start, the connection is instantiated such that each -CIDR block serves as an instance's -right - -value. The system treats the -resulting instances as normal connections. -

- -For example, given a suitable connection definition -private, - -and the file -/etc/ipsec.d/policy/private - -with an entry 192.0.2.3, -the system creates a connection instance -private#192.0.2.3. - -This connection inherits all details from -private, - -except that its right client is 192.0.2.3. -  -

DEFAULT POLICY GROUPS

- -

- -The standard FreeS/WAN install includes several policy groups -which provide a way of classifying possible peers into IPsec security classes: -private - -(talk encrypted only), -private-or-clear - -(prefer encryption), -clear-or-private - -(respond to requests for encryption), -clear - -and -block. - -Implicit policy groups apply to the local host only, -and are implemented by the -IMPLICIT CONNECTIONS - -described above. -  -

CHOOSING A CONNECTION

- -

- -When choosing a connection to apply to an outbound packet caught with a -%trap, - -the system prefers the one with the most specific eroute that -includes the packet's source and destination IP addresses. -Source subnets are examined before destination subnets. -For initiating, only routed connections are considered. For responding, -unrouted but added connections are considered. -

- -When choosing a connection to use to respond to a negotiation which -doesn't match an ordinary conn, an opportunistic connection -may be instantiated. Eventually, its instance will be /32 -> /32, but -for earlier stages of the negotiation, there will not be enough -information about the client subnets to complete the instantiation. -  -

FILES

- -
-/etc/ipsec.conf
-/etc/ipsec.d/policies/clear
-/etc/ipsec.d/policies/clear-or-private
-/etc/ipsec.d/policies/private-or-clear
-/etc/ipsec.d/policies/private
-/etc/ipsec.d/policies/block
-
- -  -

SEE ALSO

- -ipsec(8), ipsec_ttoaddr(8), ipsec_auto(8), ipsec_manual(8), ipsec_rsasigkey(8) -  -

HISTORY

- -Designed for the FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -

- -When -type - -or -failureshunt - -is set to -drop - -or -reject, - -FreeS/WAN blocks outbound packets using eroutes, but assumes inbound -blocking is handled by the firewall. FreeS/WAN offers firewall hooks -via an ``updown'' script. However, the default -ipsec _updown - -provides no help in controlling a modern firewall. -

- -Including attributes of the keying channel -(authentication methods, -ikelifetime, - -etc.) -as an attribute of a connection, -rather than of a participant pair, is dubious and incurs limitations. -

- -Ipsec_manual - -is not nearly as generous about the syntax of subnets, -addresses, etc. as the usual FreeS/WAN user interfaces. -Four-component dotted-decimal must be used for all addresses. -It -is - -smart enough to translate bit-count netmasks to dotted-decimal form. -

- -It would be good to have a line-continuation syntax, -especially for the very long lines involved in -RSA signature keys. -

- -The ability to specify different identities, -authby, - -and public keys for different automatic-keyed connections -between the same participants is misleading; -this doesn't work dependably because the identity of the participants -is not known early enough. -This is especially awkward for the ``Road Warrior'' case, -where the remote IP address is specified as -0.0.0.0, - -and that is considered to be the ``participant'' for such connections. -

- -In principle it might be necessary to control MTU on an -interface-by-interface basis, -rather than with the single global override that -overridemtu - -provides. -

- -A number of features which could be implemented in -both manual and automatic keying -actually are not yet implemented for manual keying. -This is unlikely to be fixed any time soon. -

- -If conns are to be added before DNS is available, -left=FQDN, -leftnextop=FQDN, -and -leftrsasigkey=%dnsonload - -will fail. -ipsec_pluto(8) - -does not actually use the public key for our side of a conn but it -isn't generally known at a add-time which side is ours (Road Warrior -and Opportunistic conns are currently exceptions). -

- -The myid option does not affect explicit ipsec auto --add or ipsec auto --replace commands for implicit conns. -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
CONN SECTIONS
-
-
CONN PARAMETERS: GENERAL
-
CONN PARAMETERS: AUTOMATIC KEYING
-
CONN PARAMETERS: MANUAL KEYING
-
-
CONFIG SECTIONS
-
IMPLICIT CONNS
-
POLICY GROUP FILES
-
DEFAULT POLICY GROUPS
-
CHOOSING A CONNECTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec.secrets.5.html b/doc/manpage.d/ipsec.secrets.5.html deleted file mode 100644 index 8abc1f492..000000000 --- a/doc/manpage.d/ipsec.secrets.5.html +++ /dev/null @@ -1,227 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC.SECRETS - -

IPSEC.SECRETS

-Section: File Formats (5)
Updated: 28 March 1999
Index -Return to Main Contents
- -  -

NAME

- -ipsec.secrets - secrets for IKE/IPsec authentication -  -

DESCRIPTION

- -The file ipsec.secrets holds a table of secrets. -These secrets are used by ipsec_pluto(8), the FreeS/WAN Internet Key -Exchange daemon, to authenticate other hosts. -Currently there are two kinds of secrets: preshared secrets and - -RSA private keys. -

- -It is vital that these secrets be protected. The file should be owned -by the super-user, -and its permissions should be set to block all access by others. -

- -The file is a sequence of entries and include directives. -Here is an example. Each entry or directive must start at the -left margin, but if it continues beyond a single line, each continuation -line must be indented. -

- -

-
-# sample /etc/ipsec.secrets file for 10.1.0.1
-10.1.0.1 10.2.0.1: PSK "secret shared by two hosts"
-
-# an entry may be split across lines,
-# but indentation matters
-www.xs4all.nl @www.kremvax.ru
-    10.6.0.1 10.7.0.1 1.8.0.1: PSK "secret shared by 5"
-
-# an RSA private key.
-# note that the lines are too wide for a
-# man page, so ... has been substituted for
-# the truncated part
-@my.com: rsa {
-    Modulus: 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt...
-    PublicExponent: 0sAw==
-    PrivateExponent: 0shlGbVR1m8Z+7rhzSyenCaBN...
-    Prime1: 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l...
-    Prime2: 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0...
-    Exponent1: 0soaXj85ihM5M2inVf/NfHmtLutVz4r...
-    Exponent2: 0sjdAL9VFizF+BKU4ohguJFzOd55OG6...
-    Coefficient: 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ...
-    }
-
-include ipsec.*.secrets # get secrets from other files
-
- -
- -

- -Each entry in the file is a list of indices, followed by a secret. -The two parts are separated by a colon (:) that is -followed by whitespace or a newline. For compatability -with the previous form of this file, if the key part is just a -double-quoted string the colon may be left out. -

- -An index is an IP address, or a Fully Qualified Domain Name, user@FQDN, -%any or %any6 (other kinds may come). An IP address may be written -in the familiar dotted quad form or as a domain name to be looked up -when the file is loaded -(or in any of the forms supported by the FreeS/WAN ipsec_ttoaddr(3) -routine). In many cases it is a bad idea to use domain names because -the name server may not be running or may be insecure. To denote a -Fully Qualified Domain Name (as opposed to an IP address denoted by -its domain name), precede the name with an at sign (@). -

- -Matching IDs with indices is fairly straightforward: they have to be -equal. In the case of a ``Road Warrior'' connection, if an equal -match is not found for the Peer's ID, and it is in the form of an IP -address, an index of %any will match the peer's IP address if IPV4 -and %any6 will match a the peer's IP address if IPV6. -Currently, the obsolete notation 0.0.0.0 may be used in place of -%any. -

- -An additional complexity -arises in the case of authentication by preshared secret: the -responder will need to look up the secret before the Peer's ID payload has -been decoded, so the ID used will be the IP address. -

- -To authenticate a connection between two hosts, the entry that most -specifically matches the host and peer IDs is used. An entry with no -index will match any host and peer. More specifically, an entry with one index will -match a host and peer if the index matches the host's ID (the peer isn't -considered). Still more specifically, an entry with multiple indices will match a host and -peer if the host ID and peer ID each match one of the indices. If the key -is for an asymmetric authentication technique (i.e. a public key -system such as RSA), an entry with multiple indices will match a host -and peer even if only the host ID matches an index (it is presumed that the -multiple indices are all identities of the host). -It is acceptable for two entries to be the best match as -long as they agree about the secret or private key. -

- -Authentication by preshared secret requires that both systems find the -identical secret (the secret is not actually transmitted by the IKE -protocol). If both the host and peer appear in the index list, the -same entry will be suitable for both systems so verbatim copying -between systems can be used. This naturally extends to larger groups -sharing the same secret. Thus multiple-index entries are best for PSK -authentication. -

- -Authentication by RSA Signatures requires that each host have its own private -key. A host could reasonably use a different private keys -for different interfaces and for different peers. But it would not -be normal to share entries between systems. Thus thus no-index and -one-index forms of entry often make sense for RSA Signature authentication. -

- -The key part of an entry may start with a token indicating the kind of -key. ``RSA'' signifies RSA private key and ``PSK'' signifies -PreShared Key (case is ignored). For compatability with previous -forms of this file, PSK is the default. -

- -A preshared secret is most conveniently represented as a sequence of -characters, delimited by the double-quote -character ("). The sequence cannot contain a newline or -double-quote. Strictly speaking, the secret is actually the sequence -of bytes that is used in the file to represent the sequence of -characters (excluding the delimiters). -A preshared secret may also be represented, without quotes, in any form supported by -ipsec_ttodata(3). -

- -An RSA private key is a composite of eight generally large numbers. The notation -used is a brace-enclosed list of field name and value pairs (see the example above). -A suitable key, in a suitable format, may be generated by ipsec_rsasigkey(8). -The structure is very similar to that used by BIND 8.2.2 or later, but note that -the numbers must have a ``0s'' prefix if they are in base 64. The order of -the fields is fixed. -

- -The first token an entry must start in -the first column of its line. Subsequent tokens must be -separated by whitespace, -except for a colon token, which only needs to be followed by whitespace. -A newline is taken as whitespace, but every -line of an entry after the first must be indented. -

- -Whitespace at the end of a line is ignored (except in the 0t -notation for a key). At the start of line or -after whitespace, # and the following text up to the end of the -line is treated as a comment. Within entries, all lines must be -indented (except for lines with no tokens). -Outside entries, no line may be indented (this is to make sure that -the file layout reflects its structure). -

- -An include directive causes the contents of the named file to be processed -before continuing with the current file. The filename is subject to -``globbing'' as in sh(1), so every file with a matching name -is processed. Includes may be nested to a modest -depth (10, currently). If the filename doesn't start with a /, the -directory containing the current file is prepended to the name. The -include directive is a line that starts with the word include, -followed by whitespace, followed by the filename (which must not contain -whitespace). -  -

FILES

- -/etc/ipsec.secrets -  -

SEE ALSO

- -The rest of the FreeS/WAN distribution, in particular -ipsec.conf(5), -ipsec(8), -ipsec_newhostkey(8), -ipsec_rsasigkey(8), -ipsec_showhostkey(8), -ipsec_auto(8) --rereadsecrets, -and ipsec_pluto(8) --listen,. -
- -BIND 8.2.2 or later, ftp://ftp.isc.org/isc/bind/src/ -  -

HISTORY

- -Designed for the FreeS/WAN project -<http://www.freeswan.org> -by D. Hugh Redelmeier. -  -

BUGS

- -If an ID is 0.0.0.0, it will match %any; -if it is 0::0, it will match %any6. -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__confread.8.html b/doc/manpage.d/ipsec__confread.8.html deleted file mode 100644 index ecc120c7e..000000000 --- a/doc/manpage.d/ipsec__confread.8.html +++ /dev/null @@ -1,58 +0,0 @@ -Content-type: text/html - -Manpage of _CONFREAD - -

_CONFREAD

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _confread - internal routing to parse config file -  -

DESCRIPTION

- -_confread - -is an internal script used for parsing /etc/ipsec.conf into a canonical format. -  -

SEE ALSO

- -ipsec(8), ipsec_conf(8) -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Program written by Henry Spencer. - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__copyright.8.html b/doc/manpage.d/ipsec__copyright.8.html deleted file mode 100644 index 7f78b3feb..000000000 --- a/doc/manpage.d/ipsec__copyright.8.html +++ /dev/null @@ -1,62 +0,0 @@ -Content-type: text/html - -Manpage of _COPYRIGHT - -

_COPYRIGHT

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _copyright - prints FreeSWAN copyright -  -

DESCRIPTION

- -_copyright - -outputs the FreeSWAN copyright, and version numbers for "ipsec --copyright" -  -

SEE ALSO

- -ipsec(8) -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Michael Richardson. Program written by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__include.8.html b/doc/manpage.d/ipsec__include.8.html deleted file mode 100644 index d85ee7852..000000000 --- a/doc/manpage.d/ipsec__include.8.html +++ /dev/null @@ -1,67 +0,0 @@ -Content-type: text/html - -Manpage of _INCLUDE - -

_INCLUDE

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _include - internal script to process config files -  -

DESCRIPTION

- -_include - -is used by -_confread - -to process -include - -directives in /etc/ipsec.conf. -  -

SEE ALSO

- -ipsec(8), ipsec__confread(8) -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Program written by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__keycensor.8.html b/doc/manpage.d/ipsec__keycensor.8.html deleted file mode 100644 index 22e574932..000000000 --- a/doc/manpage.d/ipsec__keycensor.8.html +++ /dev/null @@ -1,64 +0,0 @@ -Content-type: text/html - -Manpage of _KEYCENSOR - -

_KEYCENSOR

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _keycensor - internal routine to remove sensitive information -  -

DESCRIPTION

- -_keycensor - -is used by -ipsec barf - -to process the /etc/ipsec.secrets file, removing private key info. -  -

SEE ALSO

- -ipsec(8), ipsec_barf(8) -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__plutoload.8.html b/doc/manpage.d/ipsec__plutoload.8.html deleted file mode 100644 index 2c4968300..000000000 --- a/doc/manpage.d/ipsec__plutoload.8.html +++ /dev/null @@ -1,64 +0,0 @@ -Content-type: text/html - -Manpage of _PLUTOLOAD - -

_PLUTOLOAD

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _plutoload - internal script to start pluto -  -

DESCRIPTION

- -_plutoload - -is called by -_plutorun - -to actually start the pluto executable. -  -

SEE ALSO

- -ipsec(8), ipsec_setup(8), ipsec__realsetup(8), ipsec__plutorun(8) -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__plutorun.8.html b/doc/manpage.d/ipsec__plutorun.8.html deleted file mode 100644 index 1b5a1da11..000000000 --- a/doc/manpage.d/ipsec__plutorun.8.html +++ /dev/null @@ -1,70 +0,0 @@ -Content-type: text/html - -Manpage of _PLUTORUN - -

_PLUTORUN

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _plutorun - internal script to start pluto -  -

DESCRIPTION

- -_plutorun - -is called by -_realsetup - -to configure and bring up -ipsec_pluto(8). - -It calls -_plutoload - -to invoke pluto, and watches to makes sure that pluto is restarted if it fails. -  -

SEE ALSO

- -ipsec(8), ipsec_setup(8), ipsec__realsetup(8), ipsec__plutoload(8), ipsec_pluto(8). -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program written by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__realsetup.8.html b/doc/manpage.d/ipsec__realsetup.8.html deleted file mode 100644 index f45bec647..000000000 --- a/doc/manpage.d/ipsec__realsetup.8.html +++ /dev/null @@ -1,68 +0,0 @@ -Content-type: text/html - -Manpage of _REALSETUP - -

_REALSETUP

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _realsetup - internal routine to start FreeS/WAN. -  -

DESCRIPTION

- -_realsetup - -is called by the system init scripts to start the FreeS/WAN -system. It starts -KLIPS - -(the kernel component) and -pluto - -(the userspace keying component). -  -

SEE ALSO

- -ipsec(8), ipsec__klipsstart(8), ipsec__plutorun(8). -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__secretcensor.8.html b/doc/manpage.d/ipsec__secretcensor.8.html deleted file mode 100644 index 6c6ea312d..000000000 --- a/doc/manpage.d/ipsec__secretcensor.8.html +++ /dev/null @@ -1,65 +0,0 @@ -Content-type: text/html - -Manpage of _SECRETCENSOR - -

_SECRETCENSOR

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _secretcensor - internal routing to sanitize files -  -

DESCRIPTION

- -_secretcensor - -is called by -ipsec barf - -to process the /etc/ipsec.secrets file to remove the private key components -from the file prior to revealing the contents. -  -

SEE ALSO

- -ipsec(8), ipsec_barf(8). -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__startklips.8.html b/doc/manpage.d/ipsec__startklips.8.html deleted file mode 100644 index 3ad565e57..000000000 --- a/doc/manpage.d/ipsec__startklips.8.html +++ /dev/null @@ -1,63 +0,0 @@ -Content-type: text/html - -Manpage of _STARTKLIPS - -

_STARTKLIPS

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _startklips - internal script to bring up kernel components -  -

DESCRIPTION

- -_startklips - -brings up the FreeS/WAN kernel component. This involves loading any -required modules, attaching and configuring the ipsecX pseudo-devices and -attaching the pseudo-devices to the physical devices. -  -

SEE ALSO

- -ipsec(8), ipsec_tncfg(8). -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec__updown.8.html b/doc/manpage.d/ipsec__updown.8.html deleted file mode 100644 index 73bf8a343..000000000 --- a/doc/manpage.d/ipsec__updown.8.html +++ /dev/null @@ -1,63 +0,0 @@ -Content-type: text/html - -Manpage of _UPDOWN - -

_UPDOWN

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec _updown - klips manipulation script -  -

SYNOPSIS

- -_updown - -is invoked by pluto when it has brought up a new connection. This script -is used to insert the appropriate routing entries for IPsec operation. -The interface to the script is documented in the pluto man page. -  -

SEE ALSO

- -ipsec(8), ipsec_pluto(8). -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program written by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrbytesof.3.html b/doc/manpage.d/ipsec_addrbytesof.3.html deleted file mode 100644 index ca1f857e7..000000000 --- a/doc/manpage.d/ipsec_addrbytesof.3.html +++ /dev/null @@ -1,232 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITADDR - -

IPSEC_INITADDR

-Section: C Library Functions (3)
Updated: 11 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initaddr - initialize an ip_address -
- -ipsec addrtypeof - get address type of an ip_address -
- -ipsec addrlenof - get length of address within an ip_address -
- -ipsec addrbytesof - get copy of address within an ip_address -
- -ipsec addrbytesptr - get pointer to address within an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *dst); - -
- -int addrtypeof(const ip_address *src); - -
- -size_t addrlenof(const ip_address *src); - -
- -size_t addrbytesof(const ip_address *src, - -
-  -unsigned char *dst, size_t dstlen); - -
- -size_t addrbytesptr(const ip_address *src, - -
-  -const unsigned char **dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_address - -to contain one of the (currently two) types of IP address. -These functions provide basic tools for creating and examining this type. -

- -Initaddr - -initializes a variable -*dst - -of type -ip_address - -from an address -(in network byte order, -indicated by a pointer -src - -and a length -srclen) - -and an address family -af - -(typically -AF_INET - -or -AF_INET6). - -The length must be consistent with the address family. -

- -Addrtypeof - -returns the address type of an address, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Addrlenof - -returns the size (in bytes) of the address within an -ip_address, - -to permit storage allocation etc. -

- -Addrbytesof - -copies the address within the -ip_address - -src - -to the buffer indicated by the pointer -dst - -and the length -dstlen, - -and returns the address length (in bytes). -If the address will not fit, -as many bytes as will fit are copied; -the returned length is still the full length. -It is the caller's responsibility to check the -returned value to ensure that there was enough room. -

- -Addrbytesptr - -sets -*dst - -to a pointer to the internal address within the -ip_address, - -and returns the address length (in bytes). -If -dst - -is -NULL, - -it just returns the address length. -The pointer points to -const - -to discourage misuse. -

- -Initaddr - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -The functions which return -size_t - -return -0 - -for a failure. -  -

SEE ALSO

- -inet(3), ipsec_ttoaddr(3) -  -

DIAGNOSTICS

- -An unknown address family is a fatal error for any of these functions -except -addrtypeof. - -An address-size mismatch is a fatal error for -initaddr. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Addrtypeof - -should probably have been named -addrfamilyof. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrbytesptr.3.html b/doc/manpage.d/ipsec_addrbytesptr.3.html deleted file mode 100644 index ca1f857e7..000000000 --- a/doc/manpage.d/ipsec_addrbytesptr.3.html +++ /dev/null @@ -1,232 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITADDR - -

IPSEC_INITADDR

-Section: C Library Functions (3)
Updated: 11 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initaddr - initialize an ip_address -
- -ipsec addrtypeof - get address type of an ip_address -
- -ipsec addrlenof - get length of address within an ip_address -
- -ipsec addrbytesof - get copy of address within an ip_address -
- -ipsec addrbytesptr - get pointer to address within an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *dst); - -
- -int addrtypeof(const ip_address *src); - -
- -size_t addrlenof(const ip_address *src); - -
- -size_t addrbytesof(const ip_address *src, - -
-  -unsigned char *dst, size_t dstlen); - -
- -size_t addrbytesptr(const ip_address *src, - -
-  -const unsigned char **dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_address - -to contain one of the (currently two) types of IP address. -These functions provide basic tools for creating and examining this type. -

- -Initaddr - -initializes a variable -*dst - -of type -ip_address - -from an address -(in network byte order, -indicated by a pointer -src - -and a length -srclen) - -and an address family -af - -(typically -AF_INET - -or -AF_INET6). - -The length must be consistent with the address family. -

- -Addrtypeof - -returns the address type of an address, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Addrlenof - -returns the size (in bytes) of the address within an -ip_address, - -to permit storage allocation etc. -

- -Addrbytesof - -copies the address within the -ip_address - -src - -to the buffer indicated by the pointer -dst - -and the length -dstlen, - -and returns the address length (in bytes). -If the address will not fit, -as many bytes as will fit are copied; -the returned length is still the full length. -It is the caller's responsibility to check the -returned value to ensure that there was enough room. -

- -Addrbytesptr - -sets -*dst - -to a pointer to the internal address within the -ip_address, - -and returns the address length (in bytes). -If -dst - -is -NULL, - -it just returns the address length. -The pointer points to -const - -to discourage misuse. -

- -Initaddr - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -The functions which return -size_t - -return -0 - -for a failure. -  -

SEE ALSO

- -inet(3), ipsec_ttoaddr(3) -  -

DIAGNOSTICS

- -An unknown address family is a fatal error for any of these functions -except -addrtypeof. - -An address-size mismatch is a fatal error for -initaddr. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Addrtypeof - -should probably have been named -addrfamilyof. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrcmp.3.html b/doc/manpage.d/ipsec_addrcmp.3.html deleted file mode 100644 index 93ac522cd..000000000 --- a/doc/manpage.d/ipsec_addrcmp.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrinsubnet.3.html b/doc/manpage.d/ipsec_addrinsubnet.3.html deleted file mode 100644 index 93ac522cd..000000000 --- a/doc/manpage.d/ipsec_addrinsubnet.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrlenof.3.html b/doc/manpage.d/ipsec_addrlenof.3.html deleted file mode 100644 index ca1f857e7..000000000 --- a/doc/manpage.d/ipsec_addrlenof.3.html +++ /dev/null @@ -1,232 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITADDR - -

IPSEC_INITADDR

-Section: C Library Functions (3)
Updated: 11 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initaddr - initialize an ip_address -
- -ipsec addrtypeof - get address type of an ip_address -
- -ipsec addrlenof - get length of address within an ip_address -
- -ipsec addrbytesof - get copy of address within an ip_address -
- -ipsec addrbytesptr - get pointer to address within an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *dst); - -
- -int addrtypeof(const ip_address *src); - -
- -size_t addrlenof(const ip_address *src); - -
- -size_t addrbytesof(const ip_address *src, - -
-  -unsigned char *dst, size_t dstlen); - -
- -size_t addrbytesptr(const ip_address *src, - -
-  -const unsigned char **dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_address - -to contain one of the (currently two) types of IP address. -These functions provide basic tools for creating and examining this type. -

- -Initaddr - -initializes a variable -*dst - -of type -ip_address - -from an address -(in network byte order, -indicated by a pointer -src - -and a length -srclen) - -and an address family -af - -(typically -AF_INET - -or -AF_INET6). - -The length must be consistent with the address family. -

- -Addrtypeof - -returns the address type of an address, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Addrlenof - -returns the size (in bytes) of the address within an -ip_address, - -to permit storage allocation etc. -

- -Addrbytesof - -copies the address within the -ip_address - -src - -to the buffer indicated by the pointer -dst - -and the length -dstlen, - -and returns the address length (in bytes). -If the address will not fit, -as many bytes as will fit are copied; -the returned length is still the full length. -It is the caller's responsibility to check the -returned value to ensure that there was enough room. -

- -Addrbytesptr - -sets -*dst - -to a pointer to the internal address within the -ip_address, - -and returns the address length (in bytes). -If -dst - -is -NULL, - -it just returns the address length. -The pointer points to -const - -to discourage misuse. -

- -Initaddr - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -The functions which return -size_t - -return -0 - -for a failure. -  -

SEE ALSO

- -inet(3), ipsec_ttoaddr(3) -  -

DIAGNOSTICS

- -An unknown address family is a fatal error for any of these functions -except -addrtypeof. - -An address-size mismatch is a fatal error for -initaddr. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Addrtypeof - -should probably have been named -addrfamilyof. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrtoa.3.html b/doc/manpage.d/ipsec_addrtoa.3.html deleted file mode 100644 index 8f0d765e5..000000000 --- a/doc/manpage.d/ipsec_addrtoa.3.html +++ /dev/null @@ -1,448 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOADDR - -

IPSEC_ATOADDR

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII -
- -ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoaddr(const char *src, size_t srclen, - -
-  -struct in_addr *addr); - -
- -size_t addrtoa(struct in_addr addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *atosubnet(const char *src, size_t srclen, - -
-  -struct in_addr *addr, struct in_addr *mask); - -
- -size_t subnettoa(struct in_addr addr, struct in_addr mask, - -
-  -int format, char *dst, size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttoaddr(3) - -for their replacements. -

- -Atoaddr - -converts an ASCII name or dotted-decimal address into a binary address -(in network byte order). -Addrtoa - -does the reverse conversion, back to an ASCII dotted-decimal address. -Atosubnet - -and -subnettoa - -do likewise for the ``address/mask'' ASCII form used to write a -specification of a subnet. -

- -An address is specified in ASCII as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -ASCII-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of -addrtoa - -is always complete and does not contain leading zeros. -

- -The letters in -a hexadecimal address may be uppercase or lowercase or any mixture thereof. -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -Name lookup resorts to -getnetbyname(3) - -only if -gethostbyname(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -atoaddr. - -In addition, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0. - -

- -Atosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettoa - -generates the decimal-integer-bit-count -form of the mask, -with no leading zeros, -unless the mask is non-contiguous. -

- -The -srclen - -parameter of -atoaddr - -and -atosubnet - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -addrtoa - -and -subnettoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOA_BUF - -and -SUBNETTOA_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtoa - -and -subnettoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available. -This parameter is a hedge against future needs. -

- -The ASCII-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-ASCII functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoaddr - -are: -empty input; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal form; -dotted-decimal component too large to fit in 8 bits. -

- -Fatal errors in -atosubnet - -are: -no -/ - -in -src; - -atoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtoa - -and -subnettoa - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -The restriction of ASCII-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The ASCII-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrtosubnet.3.html b/doc/manpage.d/ipsec_addrtosubnet.3.html deleted file mode 100644 index e442a9100..000000000 --- a/doc/manpage.d/ipsec_addrtosubnet.3.html +++ /dev/null @@ -1,238 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITSUBNET - -

IPSEC_INITSUBNET

-Section: C Library Functions (3)
Updated: 12 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initsubnet - initialize an ip_subnet -
- -ipsec addrtosubnet - initialize a singleton ip_subnet -
- -ipsec subnettypeof - get address type of an ip_subnet -
- -ipsec masktocount - convert subnet mask to bit count -
- -ipsec networkof - get base address of an ip_subnet -
- -ipsec maskof - get subnet mask of an ip_subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initsubnet(const ip_address *addr, - -
-  -int maskbits, int clash, ip_subnet *dst); - -
- -const char *addrtosubnet(const ip_address *addr, - -
-  -ip_subnet *dst); - -

-int subnettypeof(const ip_subnet *src); - -
- -int masktocount(const ip_address *src); - -
- -void networkof(const ip_subnet *src, ip_address *dst); - -
- -void maskof(const ip_subnet *src, ip_address *dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_subnet - -to contain a description of an IP subnet -(base address plus mask). -These functions provide basic tools for creating and examining this type. -

- -Initsubnet - -initializes a variable -*dst - -of type -ip_subnet - -from a base address and -a count of mask bits. -The -clash - -parameter specifies what to do if the base address includes -1 - -bits outside the prefix specified by the mask -(that is, in the ``host number'' part of the address): -

-
-
'0'
-zero out host-number bits -
'x'
-non-zero host-number bits are an error -
-
- -

- -Initsubnet - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -Addrtosubnet - -initializes an -ip_subnet - -variable -*dst - -to a ``singleton subnet'' containing the single address -*addr. - -It returns -NULL - -for success and -a pointer to a string-literal error message for failure. -

- -Subnettypeof - -returns the address type of a subnet, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Masktocount - -converts a subnet mask, expressed as an address, to a bit count -suitable for use with -initsubnet. - -It returns --1 - -for error; see DIAGNOSTICS. -

- -Networkof - -fills in -*dst - -with the base address of subnet -src. - -

- -Maskof - -fills in -*dst - -with the subnet mask of subnet -src, - -expressed as an address. -  -

SEE ALSO

- -inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -initsubnet - -are: -unknown address family; -unknown -clash - -value; -impossible mask bit count; -non-zero host-number bits and -clash - -is -'x'. - -Fatal errors in -addrtosubnet - -are: -unknown address family. -Fatal errors in -masktocount - -are: -unknown address family; -mask bits not contiguous. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrtot.3.html b/doc/manpage.d/ipsec_addrtot.3.html deleted file mode 100644 index eccb946e6..000000000 --- a/doc/manpage.d/ipsec_addrtot.3.html +++ /dev/null @@ -1,569 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOADDR - -

IPSEC_TTOADDR

-Section: C Library Functions (3)
Updated: 28 Sept 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text -
- -ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -const char *tnatoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -size_t addrtot(const ip_address *addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *ttosubnet(const char *src, size_t srclen, - -
-  -int af, ip_subnet *dst); - -
- -size_t subnettot(const ip_subnet *sub, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttoaddr - -converts a text-string name or numeric address into a binary address -(in network byte order). -Tnatoaddr - -does the same conversion, -but the only text forms it accepts are -the ``official'' forms of -numeric address (dotted-decimal for IPv4, colon-hex for IPv6). -Addrtot - -does the reverse conversion, from binary address back to a text form. -Ttosubnet - -and -subnettot - -do likewise for the ``address/mask'' form used to write a -specification of a subnet. -

- -An IPv4 address is specified in text as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -text-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of applying -addrtot - -to an IPv4 address is always complete and does not contain leading zeros. -

- -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -An IPv6 address is specified in text with -colon-hex notation (e.g. -0:56:78ab:22:33:44:55:66), - -colon-hex with -:: - -abbreviating at most one subsequence of multiple zeros (e.g. -99:ab::54:068, - -which is synonymous with -99:ab:0:0:0:0:54:68), - -or a DNS name to be looked up via -gethostbyname(3). - -The result of applying -addrtot - -to an IPv6 address will use -:: - -abbreviation if possible, -and will not contain leading zeros. -

- -The letters in hexadecimal -may be uppercase or lowercase or any mixture thereof. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname2(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -IPv4 name lookup resorts to -getnetbyname(3) - -only if -gethostbyname2(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -ttoaddr. - -In addition, and preferably, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -in IPv4 means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0 - -or -::/0 - -in IPv4 or IPv6 respectively. -

- -Ttosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettot - -always generates the decimal-integer-bit-count -form of the mask, -with no leading zeros. -

- -The -srclen - -parameter of -ttoaddr - -and -ttosubnet - -specifies the length of the text string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -af - -parameter of -ttoaddr - -and -ttosubnet - -specifies the address family of interest. -It should be either -AF_INET - -or -AF_INET6. - -

- -The -dstlen - -parameter of -addrtot - -and -subnettot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOT_BUF - -and -SUBNETTOT_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtot - -and -subnettot - -specifies what format is to be used for the conversion. -The value -0 - -(not the character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available in -subnettot. - -Addrtot - -also accepts format values -'r' - -(signifying a text form suitable for DNS reverse lookups, -e.g. -4.3.2.1.IN-ADDR.ARPA. - -for IPv4 and -RFC 2874 format for IPv6), -and -'R' - -(signifying an alternate reverse-lookup form, -an error for IPv4 and RFC 1886 format for IPv6). -Reverse-lookup names always end with a ``.''. -

- -The text-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-text functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoaddr - -are: -empty input; -unknown address family; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal or colon-hex form; -dotted-decimal or colon-hex component too large. -

- -Fatal errors in -ttosubnet - -are: -no -/ - -in -src; - -ttoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtot - -and -subnettot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -Ttoaddr - -does not support the mixed colon-hex-dotted-decimal -convention used to embed an IPv4 address in an IPv6 address. -

- -Addrtot - -always uses the -:: - -abbreviation (which can appear only once in an address) for the -first - -sequence of multiple zeros in an IPv6 address. -One can construct addresses (unlikely ones) in which this is suboptimal. -

- -Addrtot - -'r' - -conversion of an IPv6 address uses lowercase hexadecimal, -not the uppercase used in RFC 2874's examples. -It takes careful reading of RFCs 2874, 2673, and 2234 to realize -that lowercase is technically legitimate here, -and there may be software which botches this -and hence would have trouble with lowercase hex. -

- -Possibly -subnettot - -ought to recognize the -%default - -case and generate that string as its output. -Currently it doesn't. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -Tnatoaddr - -probably should enforce completeness of dotted-decimal addresses. -

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_addrtypeof.3.html b/doc/manpage.d/ipsec_addrtypeof.3.html deleted file mode 100644 index ca1f857e7..000000000 --- a/doc/manpage.d/ipsec_addrtypeof.3.html +++ /dev/null @@ -1,232 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITADDR - -

IPSEC_INITADDR

-Section: C Library Functions (3)
Updated: 11 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initaddr - initialize an ip_address -
- -ipsec addrtypeof - get address type of an ip_address -
- -ipsec addrlenof - get length of address within an ip_address -
- -ipsec addrbytesof - get copy of address within an ip_address -
- -ipsec addrbytesptr - get pointer to address within an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *dst); - -
- -int addrtypeof(const ip_address *src); - -
- -size_t addrlenof(const ip_address *src); - -
- -size_t addrbytesof(const ip_address *src, - -
-  -unsigned char *dst, size_t dstlen); - -
- -size_t addrbytesptr(const ip_address *src, - -
-  -const unsigned char **dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_address - -to contain one of the (currently two) types of IP address. -These functions provide basic tools for creating and examining this type. -

- -Initaddr - -initializes a variable -*dst - -of type -ip_address - -from an address -(in network byte order, -indicated by a pointer -src - -and a length -srclen) - -and an address family -af - -(typically -AF_INET - -or -AF_INET6). - -The length must be consistent with the address family. -

- -Addrtypeof - -returns the address type of an address, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Addrlenof - -returns the size (in bytes) of the address within an -ip_address, - -to permit storage allocation etc. -

- -Addrbytesof - -copies the address within the -ip_address - -src - -to the buffer indicated by the pointer -dst - -and the length -dstlen, - -and returns the address length (in bytes). -If the address will not fit, -as many bytes as will fit are copied; -the returned length is still the full length. -It is the caller's responsibility to check the -returned value to ensure that there was enough room. -

- -Addrbytesptr - -sets -*dst - -to a pointer to the internal address within the -ip_address, - -and returns the address length (in bytes). -If -dst - -is -NULL, - -it just returns the address length. -The pointer points to -const - -to discourage misuse. -

- -Initaddr - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -The functions which return -size_t - -return -0 - -for a failure. -  -

SEE ALSO

- -inet(3), ipsec_ttoaddr(3) -  -

DIAGNOSTICS

- -An unknown address family is a fatal error for any of these functions -except -addrtypeof. - -An address-size mismatch is a fatal error for -initaddr. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Addrtypeof - -should probably have been named -addrfamilyof. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_anyaddr.3.html b/doc/manpage.d/ipsec_anyaddr.3.html deleted file mode 100644 index 974236005..000000000 --- a/doc/manpage.d/ipsec_anyaddr.3.html +++ /dev/null @@ -1,166 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec anyaddr - get "any" address -
- -ipsec isanyaddr - test address for equality to "any" address -
- -ipsec unspecaddr - get "unspecified" address -
- -ipsec isunspecaddr - test address for equality to "unspecified" address -
- -ipsec loopbackaddr - get loopback address -
- -ipsec isloopbackaddr - test address for equality to loopback address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *anyaddr(int af, ip_address *dst); - -
- -int isanyaddr(const ip_address *src); - -
- -const char *unspecaddr(int af, ip_address *dst); - -
- -int isunspecaddr(const ip_address *src); - -
- -const char *loopbackaddr(int af, ip_address *dst); - -
- -int isloopbackaddr(const ip_address *src); - -  -

DESCRIPTION

- -These functions fill in, and test for, special values of the -ip_address - -type. -

- -Anyaddr - -fills in the destination -*dst - -with the ``any'' address of address family -af - -(normally -AF_INET - -or -AF_INET6). - -The IPv4 ``any'' address is the one embodied in the old -INADDR_ANY - -macro. -

- -Isanyaddr - -returns -1 - -if the -src - -address equals the ``any'' address, -and -0 - -otherwise. -

- -Similarly, -unspecaddr - -supplies, and -isunspecaddr - -tests for, -the ``unspecified'' address, -which may be the same as the ``any'' address. -

- -Similarly, -loopbackaddr - -supplies, and -islookbackaddr - -tests for, -the loopback address. -

- -Anyaddr, - -unspecaddr, - -and -loopbackaddr - -return -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -inet(3), ipsec_addrtot(3), ipsec_sameaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in the address-supplying functions are: -unknown address family. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_atoaddr.3.html b/doc/manpage.d/ipsec_atoaddr.3.html deleted file mode 100644 index 8f0d765e5..000000000 --- a/doc/manpage.d/ipsec_atoaddr.3.html +++ /dev/null @@ -1,448 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOADDR - -

IPSEC_ATOADDR

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII -
- -ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoaddr(const char *src, size_t srclen, - -
-  -struct in_addr *addr); - -
- -size_t addrtoa(struct in_addr addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *atosubnet(const char *src, size_t srclen, - -
-  -struct in_addr *addr, struct in_addr *mask); - -
- -size_t subnettoa(struct in_addr addr, struct in_addr mask, - -
-  -int format, char *dst, size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttoaddr(3) - -for their replacements. -

- -Atoaddr - -converts an ASCII name or dotted-decimal address into a binary address -(in network byte order). -Addrtoa - -does the reverse conversion, back to an ASCII dotted-decimal address. -Atosubnet - -and -subnettoa - -do likewise for the ``address/mask'' ASCII form used to write a -specification of a subnet. -

- -An address is specified in ASCII as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -ASCII-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of -addrtoa - -is always complete and does not contain leading zeros. -

- -The letters in -a hexadecimal address may be uppercase or lowercase or any mixture thereof. -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -Name lookup resorts to -getnetbyname(3) - -only if -gethostbyname(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -atoaddr. - -In addition, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0. - -

- -Atosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettoa - -generates the decimal-integer-bit-count -form of the mask, -with no leading zeros, -unless the mask is non-contiguous. -

- -The -srclen - -parameter of -atoaddr - -and -atosubnet - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -addrtoa - -and -subnettoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOA_BUF - -and -SUBNETTOA_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtoa - -and -subnettoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available. -This parameter is a hedge against future needs. -

- -The ASCII-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-ASCII functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoaddr - -are: -empty input; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal form; -dotted-decimal component too large to fit in 8 bits. -

- -Fatal errors in -atosubnet - -are: -no -/ - -in -src; - -atoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtoa - -and -subnettoa - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -The restriction of ASCII-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The ASCII-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_atoasr.3.html b/doc/manpage.d/ipsec_atoasr.3.html deleted file mode 100644 index 7c9e2c4aa..000000000 --- a/doc/manpage.d/ipsec_atoasr.3.html +++ /dev/null @@ -1,294 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOASR - -

IPSEC_ATOASR

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoasr - convert ASCII to Internet address, subnet, or range -
- -ipsec rangetoa - convert Internet address range to ASCII -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoasr(const char *src, size_t srclen, - -
-  -char *type, struct in_addr *addrs); - -
- -size_t rangetoa(struct in_addr *addrs, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; -there is no current equivalent, -because so far they have not proved useful. -

- -Atoasr - -converts an ASCII address, subnet, or address range -into a suitable combination of binary addresses -(in network byte order). -Rangetoa - -converts an address range back into ASCII, -using dotted-decimal form for the addresses -(the other reverse conversions are handled by -ipsec_addrtoa(3) - -and -ipsec_subnettoa(3)). - -

- -A single address can be any form acceptable to -ipsec_atoaddr(3): - -dotted decimal, DNS name, or hexadecimal number. -A subnet -specification uses the form network/mask -interpreted by -ipsec_atosubnet(3). - -

- -An address range is two -ipsec_atoaddr(3) - -addresses separated by a -... - -delimiter. -If there are four dots rather than three, the first is taken as -part of the begin address, -e.g. for a complete DNS name which ends with -. - -to suppress completion attempts. -The begin address of a range must be -less than or equal to the end address. -

- -The -srclen - -parameter of -atoasr - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -type - -parameter of -atoasr - -must point to a -char - -variable used to record which form was found. -The -addrs - -parameter must point to a two-element array of -struct in_addr - -which receives the results. -The values stored into -*type, - -and the corresponding values in the array, are: -

- - - -   *typeaddrs[0]addrs[1]
-

-address'a'address-
-
- -subnet 's'networkmask
-
- -range  'r'beginend
-

- -The -dstlen - -parameter of -rangetoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant, -RANGETOA_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -rangetoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available. -This parameter is a hedge against future needs. -

- -Atoasr - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Rangetoa - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -ipsec_atoaddr(3), ipsec_atosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoasr - -are: -empty input; -error in -ipsec_atoaddr(3) - -or -ipsec_atosubnet(3) - -during conversion; -begin address of range exceeds end address. -

- -Fatal errors in -rangetoa - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoasr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_atosa.3.html b/doc/manpage.d/ipsec_atosa.3.html deleted file mode 100644 index 9e2dc2f61..000000000 --- a/doc/manpage.d/ipsec_atosa.3.html +++ /dev/null @@ -1,347 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOSA - -

IPSEC_ATOSA

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atosa, satoa - convert IPsec Security Association IDs to and from ASCII -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atosa(const char *src, size_t srclen, - -
-  -struct sa_id *sa); - -
- -size_t satoa(struct sa_id sa, int format, - -
-  -char *dst, size_t dstlen); - -

-struct sa_id { - -
-  -struct in_addr dst; - -
-  -ipsec_spi_t spi; - -
-  -int proto; - -
- -}; - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttosa(3) - -for their replacements. -

- -Atosa - -converts an ASCII Security Association (SA) specifier into an -sa_id - -structure (containing -a destination-host address -in network byte order, -an SPI number in network byte order, and -a protocol code). -Satoa - -does the reverse conversion, back to an ASCII SA specifier. -

- -An SA is specified in ASCII with a mail-like syntax, e.g. -esp507@1.2.3.4. - -An SA specifier contains -a protocol prefix (currently -ah, - -esp, - -or -tun), - -an unsigned integer SPI number, -and an IP address. -The SPI number can be decimal or hexadecimal -(with -0x - -prefix), as accepted by -ipsec_atoul(3). - -The IP address can be any form accepted by -ipsec_atoaddr(3), - -e.g. dotted-decimal address or DNS name. -

- -As a special case, the SA specifier -%passthrough - -signifies the special SA used to indicate that packets should be -passed through unaltered. -(At present, this is a synonym for -tun0x0@0.0.0.0, - -but that is subject to change without notice.) -This form is known to both -atosa - -and -satoa, - -so the internal form of -%passthrough - -is never visible. -

- -The -<freeswan.h> - -header file supplies the -sa_id - -structure, as well as a data type -ipsec_spi_t - -which is an unsigned 32-bit integer. -(There is no consistency between kernel and user on what such a type -is called, hence the header hides the differences.) -

- -The protocol code uses the same numbers that IP does. -For user convenience, given the difficulty in acquiring the exact set of -protocol names used by the kernel, -<freeswan.h> - -defines the names -SA_ESP, - -SA_AH, - -and -SA_IPIP - -to have the same values as the kernel names -IPPROTO_ESP, - -IPPROTO_AH, - -and -IPPROTO_IPIP. - -

- -The -srclen - -parameter of -atosa - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -satoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant, -SATOA_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -satoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default -(currently -lowercase protocol prefix, lowercase hexadecimal SPI, dotted-decimal address). -The value -d - -causes the SPI to be generated in decimal instead. -

- -Atosa - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Satoa - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -ipsec_atoul(3), ipsec_atoaddr(3), inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atosa - -are: -empty input; -input too small to be a legal SA specifier; -no -@ - -in input; -unknown protocol prefix; -conversion error in -atoul - -or -atoaddr. - -

- -Fatal errors in -satoa - -are: -unknown format; unknown protocol code. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The -tun - -protocol code is a FreeS/WANism which may eventually disappear. -

- -The restriction of ASCII-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The ASCII-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_atosubnet.3.html b/doc/manpage.d/ipsec_atosubnet.3.html deleted file mode 100644 index 8f0d765e5..000000000 --- a/doc/manpage.d/ipsec_atosubnet.3.html +++ /dev/null @@ -1,448 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOADDR - -

IPSEC_ATOADDR

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII -
- -ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoaddr(const char *src, size_t srclen, - -
-  -struct in_addr *addr); - -
- -size_t addrtoa(struct in_addr addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *atosubnet(const char *src, size_t srclen, - -
-  -struct in_addr *addr, struct in_addr *mask); - -
- -size_t subnettoa(struct in_addr addr, struct in_addr mask, - -
-  -int format, char *dst, size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttoaddr(3) - -for their replacements. -

- -Atoaddr - -converts an ASCII name or dotted-decimal address into a binary address -(in network byte order). -Addrtoa - -does the reverse conversion, back to an ASCII dotted-decimal address. -Atosubnet - -and -subnettoa - -do likewise for the ``address/mask'' ASCII form used to write a -specification of a subnet. -

- -An address is specified in ASCII as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -ASCII-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of -addrtoa - -is always complete and does not contain leading zeros. -

- -The letters in -a hexadecimal address may be uppercase or lowercase or any mixture thereof. -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -Name lookup resorts to -getnetbyname(3) - -only if -gethostbyname(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -atoaddr. - -In addition, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0. - -

- -Atosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettoa - -generates the decimal-integer-bit-count -form of the mask, -with no leading zeros, -unless the mask is non-contiguous. -

- -The -srclen - -parameter of -atoaddr - -and -atosubnet - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -addrtoa - -and -subnettoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOA_BUF - -and -SUBNETTOA_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtoa - -and -subnettoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available. -This parameter is a hedge against future needs. -

- -The ASCII-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-ASCII functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoaddr - -are: -empty input; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal form; -dotted-decimal component too large to fit in 8 bits. -

- -Fatal errors in -atosubnet - -are: -no -/ - -in -src; - -atoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtoa - -and -subnettoa - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -The restriction of ASCII-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The ASCII-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_atoul.3.html b/doc/manpage.d/ipsec_atoul.3.html deleted file mode 100644 index 923a16131..000000000 --- a/doc/manpage.d/ipsec_atoul.3.html +++ /dev/null @@ -1,266 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOUL - -

IPSEC_ATOUL

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoul, ultoa - convert unsigned-long numbers to and from ASCII -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoul(const char *src, size_t srclen, - -
-  -int base, unsigned long *n); - -
- -size_t ultoa(unsigned long n, int base, char *dst, - -
-  -size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttoul(3) - -for their replacements. -

- -Atoul - -converts an ASCII number into a binary -unsigned long - -value. -Ultoa - -does the reverse conversion, back to an ASCII version. -

- -Numbers are specified in ASCII as -decimal (e.g. -123), - -octal with a leading zero (e.g. -012, - -which has value 10), -or hexadecimal with a leading -0x - -(e.g. -0x1f, - -which has value 31) -in either upper or lower case. -

- -The -srclen - -parameter of -atoul - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -base - -parameter of -atoul - -can be -8, - -10, - -or -16, - -in which case the number supplied is assumed to be of that form -(and in the case of -16, - -to lack any -0x - -prefix). -It can also be -0, - -in which case the number is examined for a leading zero -or a leading -0x - -to determine its base, -or -13 - -(halfway between 10 and 16), -which has the same effect as -0 - -except that a non-hexadecimal -number is considered decimal regardless of any leading zero. -

- -The -dstlen - -parameter of -ultoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -

- -The -base - -parameter of -ultoa - -must be -8, - -10, - -or -16. - -

- -Atoul - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Ultoa - -returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -atol(3), strtoul(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoul - -are: -empty input; -unknown -base; - -non-digit character found; -number too large for an -unsigned long. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -There is no provision for reporting an invalid -base - -parameter given to -ultoa. - -

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoul( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_auto.8.html b/doc/manpage.d/ipsec_auto.8.html deleted file mode 100644 index 68ca61bdc..000000000 --- a/doc/manpage.d/ipsec_auto.8.html +++ /dev/null @@ -1,416 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_AUTO - -

IPSEC_AUTO

-Section: Maintenance Commands (8)
Updated: 31 Jan 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec auto - control automatically-keyed IPsec connections -  -

SYNOPSIS

- -ipsec - -auto - -[ ---show - -] [ ---showonly - -] [ ---asynchronous - -] -
- -   [ ---config - -configfile -] [ ---verbose - -] -
- -   operation -connection -

-ipsec - -auto - -[ ---show - -] [ ---showonly - -] operation -  -

DESCRIPTION

- -Auto - -manipulates automatically-keyed FreeS/WAN IPsec connections, -setting them up and shutting them down -based on the information in the IPsec configuration file. -In the normal usage, -connection - -is the name of a connection specification in the configuration file; -operation - -is ---add, - ---delete, - ---replace, - ---up, - ---down, - ---route, - -or ---unroute. - -The ---ready, - ---rereadsecrets, - ---rereadgroups, - -and ---status - -operations - -do not take a connection name. -Auto - -generates suitable -commands and feeds them to a shell for execution. -

- -The ---add - -operation adds a connection specification to the internal database -within -pluto; - -it will fail if -pluto - -already has a specification by that name. -The ---delete - -operation deletes a connection specification from -pluto's - -internal database (also tearing down any connections based on it); -it will fail if the specification does not exist. -The ---replace - -operation is equivalent to ---delete - -(if there is already a specification by the given name) -followed by ---add, - -and is a convenience for updating -pluto's - -internal specification to match an external one. -(Note that a ---rereadsecrets - -may also be needed.) -The ---rereadgroups - -operation causes any changes to the policy group files to take effect -(this is currently a synonym for ---ready, - -but that may change). -None of the other operations alters the internal database. -

- -The ---up - -operation asks -pluto - -to establish a connection based on an entry in its internal database. -The ---down - -operation tells -pluto - -to tear down such a connection. -

- -Normally, -pluto - -establishes a route to the destination specified for a connection as -part of the ---up - -operation. -However, the route and only the route can be established with the ---route - -operation. -Until and unless an actual connection is established, -this discards any packets sent there, -which may be preferable to having them sent elsewhere based on a more -general route (e.g., a default route). -

- -Normally, -pluto's - -route to a destination remains in place when a ---down - -operation is used to take the connection down -(or if connection setup, or later automatic rekeying, fails). -This permits establishing a new connection (perhaps using a -different specification; the route is altered as necessary) -without having a ``window'' in which packets might go elsewhere -based on a more general route. -Such a route can be removed using the ---unroute - -operation -(and is implicitly removed by ---delete). - -

- -The ---ready - -operation tells -pluto - -to listen for connection-setup requests from other hosts. -Doing an ---up - -operation before doing ---ready - -on both ends is futile and will not work, -although this is now automated as part of IPsec startup and -should not normally be an issue. -

- -The ---status - -operation asks -pluto - -for current connection status. -The output format is ad-hoc and likely to change. -

- -The ---rereadsecrets - -operation tells -pluto - -to re-read the -/etc/ipsec.secrets - -secret-keys file, -which it normally reads only at startup time. -(This is currently a synonym for ---ready, - -but that may change.) -

- -The ---show - -option turns on the --x - -option of the shell used to execute the commands, -so each command is shown as it is executed. -

- -The ---showonly - -option causes -auto - -to show the commands it would run, on standard output, -and not run them. -

- -The ---asynchronous - -option, applicable only to the -up - -operation, -tells -pluto - -to attempt to establish the connection, -but does not delay to report results. -This is especially useful to start multiple connections in parallel -when network links are slow. -

- -The ---verbose - -option instructs -auto - -to pass through all output from -ipsec_whack(8), - -including log output that is normally filtered out as uninteresting. -

- -The ---config - -option specifies a non-standard location for the IPsec -configuration file (default -/etc/ipsec.conf). - -

- -See -ipsec.conf(5) - -for details of the configuration file. -Apart from the basic parameters which specify the endpoints and routing -of a connection (left -and -right, - -plus possibly -leftsubnet, - -leftnexthop, - -leftfirewall, - -their -right - -equivalents, -and perhaps -type), - -an -auto - -connection almost certainly needs a -keyingtries - -parameter (since the -keyingtries - -default is poorly chosen). -  -

FILES

- - - -/etc/ipsec.conf        default IPSEC configuration file
-
- -/var/run/ipsec.info   %defaultroute information
-  -

SEE ALSO

- -ipsec.conf(5), ipsec(8), ipsec_pluto(8), ipsec_whack(8), ipsec_manual(8) -  -

HISTORY

- -Written for the FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -Although an ---up - -operation does connection setup on both ends, ---down - -tears only one end of the connection down -(although the orphaned end will eventually time out). -

- -There is no support for -passthrough - -connections. -

- -A connection description which uses -%defaultroute - -for one of its -nexthop - -parameters but not the other may be falsely -rejected as erroneous in some circumstances. -

- -The exit status of ---showonly - -does not always reflect errors discovered during processing of the request. -(This is fine for human inspection, but not so good for use in scripts.) -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_barf.8.html b/doc/manpage.d/ipsec_barf.8.html deleted file mode 100644 index e7b7200e0..000000000 --- a/doc/manpage.d/ipsec_barf.8.html +++ /dev/null @@ -1,150 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_BARF - -

IPSEC_BARF

-Section: Maintenance Commands (8)
Updated: 17 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec barf - spew out collected IPsec debugging information -  -

SYNOPSIS

- -ipsec - -barf - -[ ---short - -] -

-  -

DESCRIPTION

- -Barf - -outputs (on standard output) a collection of debugging information -(contents of files, selections from logs, etc.) -related to the IPsec encryption/authentication system. -It is primarily a convenience for remote debugging, -a single command which packages up (and labels) all information -that might be relevant to diagnosing a problem in IPsec. -

- -

- -The ---short - -option limits the length of -the log portion of -barf's - -output, which can otherwise be extremely voluminous -if debug logging is turned on. -

- -Barf - -censors its output, -replacing keys -and secrets with brief checksums to avoid revealing sensitive information. -

- -Beware that the output of both commands is aimed at humans, -not programs, -and the output format is subject to change without warning. -

- -Barf - -has to figure out which files in -/var/log - -contain the IPsec log messages. -It looks for KLIPS and general log messages first in -messages - -and -syslog, - -and for Pluto messages first in -secure, - -auth.log, - -and -debug. - -In both cases, -if it does not find what it is looking for in one of those ``likely'' places, -it will resort to a brute-force search of most (non-compressed) files in -/var/log. - -  -

FILES

- -
-/proc/net/*
-/var/log/*
-/etc/ipsec.conf
-/etc/ipsec.secrets
-
- -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -Barf - -uses heuristics to try to pick relevant material out of the logs, -and relevant messages -which are not labelled with any of the tags that -barf - -looks for will be lost. -We think we've eliminated the last such case, but one never knows... -

- -Finding -updown - -scripts (so they can be included in output) is, in general, difficult. -Barf - -uses a very simple heuristic that is easily fooled. -

- -The brute-force search for the right log files can get expensive on -systems with a lot of clutter in -/var/log. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_bitstomask.3.html b/doc/manpage.d/ipsec_bitstomask.3.html deleted file mode 100644 index a67a08d83..000000000 --- a/doc/manpage.d/ipsec_bitstomask.3.html +++ /dev/null @@ -1,122 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_GOODMASK - -

IPSEC_GOODMASK

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec goodmask - is this Internet subnet mask a valid one? -
- -ipsec masktobits - convert Internet subnet mask to bit count -
- -ipsec bitstomask - convert bit count to Internet subnet mask -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int goodmask(struct in_addr mask); - -
- -int masktobits(struct in_addr mask); - -
- -struct in_addr bitstomask(int n); - -  -

DESCRIPTION

- -These functions are obsolete; -see -ipsec_masktocount(3) - -for a partial replacement. -

- -Goodmask - -reports whether the subnet -mask - -is a valid one, -i.e. consists of a (possibly empty) sequence of -1s - -followed by a (possibly empty) sequence of -0s. - -Masktobits - -takes a (valid) subnet mask and returns the number of -1 - -bits in it. -Bitstomask - -reverses this, -returning the subnet mask corresponding to bit count -n. - -

- -All masks are in network byte order. -  -

SEE ALSO

- -inet(3), ipsec_atosubnet(3) -  -

DIAGNOSTICS

- -Masktobits - -returns --1 - -for an invalid mask. -Bitstomask - -returns an all-zeros mask for a negative or out-of-range -n. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The error-reporting convention of -bitstomask - -is less than ideal; -zero is sometimes a legitimate mask. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_broadcastof.3.html b/doc/manpage.d/ipsec_broadcastof.3.html deleted file mode 100644 index 57d4a5648..000000000 --- a/doc/manpage.d/ipsec_broadcastof.3.html +++ /dev/null @@ -1,107 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SUBNETOF - -

IPSEC_SUBNETOF

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec subnetof - given Internet address and subnet mask, return subnet number -
- -ipsec hostof - given Internet address and subnet mask, return host part -
- -ipsec broadcastof - given Internet address and subnet mask, return broadcast address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-struct in_addr subnetof(struct in_addr addr, - -
-  -struct in_addr mask); - -
- -struct in_addr hostof(struct in_addr addr, - -
-  -struct in_addr mask); - -
- -struct in_addr broadcastof(struct in_addr addr, - -
-  -struct in_addr mask); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_networkof(3) - -for their replacements. -

- -Subnetof - -takes an Internet -address - -and a subnet -mask - -and returns the network part of the address -(all in network byte order). -Hostof - -similarly returns the host part, and -broadcastof - -returns the broadcast address (all-1s convention) for the network. -

- -These functions are provided to hide the Internet bit-munging inside -an API, in hopes of easing the eventual transition to IPv6. -  -

SEE ALSO

- -inet(3), ipsec_atosubnet(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Calling functions for this is more costly than doing it yourself. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_calcgoo.8.html b/doc/manpage.d/ipsec_calcgoo.8.html deleted file mode 100644 index 8379ac6a4..000000000 --- a/doc/manpage.d/ipsec_calcgoo.8.html +++ /dev/null @@ -1,78 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_CALCGOO - -

IPSEC_CALCGOO

-Section: Maintenance Commands (8)
Updated: 8 June 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec calcgoo - calculate hex value for matching modules and kernels -  -

SYNOPSIS

- -ipsec - -calcgoo - -  -

DESCRIPTION

- -calcgoo - -accepts the output of -nm -ao - -or -/proc/ksyms - -and extracts a release dependant list of symbols from it. The symbols -are processed to extract the values assigned during the MODVERSIONS -process. This process makes sure that Linux modules are only loaded -on matching kernels. - -This routine is used to find an appropriate module to match the currently -running kernel by _startklips. -  -

FILES

- -
-/proc/ksyms
-
- -  -

SEE ALSO

- -ipsec__startklips(8), genksyms(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Michael Richardson. -  -

BUGS

- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_copyright_notice.3.html b/doc/manpage.d/ipsec_copyright_notice.3.html deleted file mode 100644 index c832e01f7..000000000 --- a/doc/manpage.d/ipsec_copyright_notice.3.html +++ /dev/null @@ -1,94 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_VERSION - -

IPSEC_VERSION

-Section: C Library Functions (3)
Updated: 21 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ipsec_version_code - get IPsec version code -
- -ipsec ipsec_version_string - get full IPsec version string -
- -ipsec ipsec_copyright_notice - get IPsec copyright notice -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ipsec_version_code(void); - -
- -const char *ipsec_version_string(void); - -
- -const char **ipsec_copyright_notice(void); - -  -

DESCRIPTION

- -These functions provide information on version numbering and copyright -of the Linux FreeS/WAN IPsec implementation. -

- -Ipsec_version_code - -returns a pointer to a string constant -containing the current IPsec version code, -such as ``1.92'' or ``snap2001Nov19b''. -

- -Ipsec_version_string - -returns a pointer to a string constant giving a full version identification, -consisting of the version code preceded by a prefix identifying the software, -e.g. ``Linux FreeS/WAN 1.92''. -

- -Ipsec_copyright_notice - -returns a pointer to a vector of pointers, -terminated by a -NULL, - -which is the text of a suitable copyright notice. -Each pointer points to a string constant (possibly empty) which is one line -of the somewhat-verbose copyright notice. -The strings are NUL-terminated and do not contain a newline; -supplying suitable line termination for the output device is -the caller's responsibility. -  -

SEE ALSO

- -ipsec(8) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_datatot.3.html b/doc/manpage.d/ipsec_datatot.3.html deleted file mode 100644 index 628558001..000000000 --- a/doc/manpage.d/ipsec_datatot.3.html +++ /dev/null @@ -1,439 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTODATA - -

IPSEC_TTODATA

-Section: C Library Functions (3)
Updated: 16 August 2003
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttodata, datatot - convert binary data bytes from and to text formats -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttodata(const char *src, size_t srclen, - -
-  -int base, char *dst, size_t dstlen, size_t *lenp); - -
- -const char *ttodatav(const char *src, size_t srclen, - -
-  -int base, char *dst, size_t dstlen, size_t *lenp, - -
-  -char *errp, size_t errlen, int flags); - -
- -size_t datatot(const char *src, size_t srclen, - -
-  -int format, char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttodata, - -ttodatav, - -and -datatot - -convert arbitrary binary data (e.g. encryption or authentication keys) -from and to more-or-less human-readable text formats. -

- -Currently supported formats are hexadecimal, base64, and characters. -

- -A hexadecimal text value begins with a -0x - -(or -0X) - -prefix and continues with two-digit groups -of hexadecimal digits (0-9, and a-f or A-F), -each group encoding the value of one binary byte, high-order digit first. -A single -_ - -(underscore) -between consecutive groups is ignored, permitting punctuation to improve -readability; doing this every eight digits seems about right. -

- -A base64 text value begins with a -0s - -(or -0S) - -prefix -and continues with four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), -each group encoding the value of three binary bytes as described in -section 6.8 of RFC 2045. -If -flags - -has the -TTODATAV_IGNORESPACE - -bit on, blanks are ignore (after the prefix). -Note that the last one or two digits of a base64 group can be -= - -to indicate that fewer than three binary bytes are encoded. -

- -A character text value begins with a -0t - -(or -0T) - -prefix -and continues with text characters, each being the value of one binary byte. -

- -All these functions basically copy data from -src - -(whose size is specified by -srclen) - -to -dst - -(whose size is specified by -dstlen), - -doing the conversion en route. -If the result will not fit in -dst, - -it is truncated; -under no circumstances are more than -dstlen - -bytes of result written to -dst. - -Dstlen - -can be zero, in which case -dst - -need not be valid and no result bytes are written at all. -

- -The -base - -parameter of -ttodata - -and -ttodatav - -specifies what format the input is in; -normally it should be -0 - -to signify that this gets figured out from the prefix. -Values of -16, - -64, - -and -256 - -respectively signify hexadecimal, base64, and character-text formats -without prefixes. -

- -The -format - -parameter of -datatot, - -a single character used as a type code, -specifies which text format is wanted. -The value -0 - -(not ASCII -'0', - -but a zero value) specifies a reasonable default. -Other currently-supported values are: -

-
-
'x' - -
-continuous lower-case hexadecimal with a -0x - -prefix -
'h' - -
-lower-case hexadecimal with a -0x - -prefix and a -_ - -every eight digits -
':' - -
-lower-case hexadecimal with no prefix and a -: - -(colon) every two digits -
16 - -
-lower-case hexadecimal with no prefix or -_ - -
's' - -
-continuous base64 with a -0s - -prefix -
64 - -
-continuous base64 with no prefix -
-
- -

- -The default format is currently -'h'. - -

- -Ttodata - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -On success, -if and only if -lenp - -is non-NULL, -*lenp - -is set to the number of bytes required to contain the full untruncated result. -It is the caller's responsibility to check this against -dstlen - -to determine whether he has obtained a complete result. -The -*lenp - -value is correct even if -dstlen - -is zero, which offers a way to determine how much space would be needed -before having to allocate any. -

- -Ttodatav - -is just like -ttodata - -except that in certain cases, -if -errp - -is non-NULL, -the buffer pointed to by -errp - -(whose length is given by -errlen) - -is used to hold a more detailed error message. -The return value is NULL for success, -and is either -errp - -or a pointer to a string literal for failure. -If the size of the error-message buffer is -inadequate for the desired message, -ttodatav - -will fall back on returning a pointer to a literal string instead. -The -freeswan.h - -header file defines a constant -TTODATAV_BUF - -which is the size of a buffer large enough for worst-case results. -

- -The normal return value of -datatot - -is the number of bytes required -to contain the full untruncated result. -It is the caller's responsibility to check this against -dstlen - -to determine whether he has obtained a complete result. -The return value is correct even if -dstlen - -is zero, which offers a way to determine how much space would be needed -before having to allocate any. -A return value of -0 - -signals a fatal error of some kind -(see DIAGNOSTICS). -

- -A zero value for -srclen - -in -ttodata - -(but not -datatot!) - -is synonymous with -strlen(src). - -A non-zero -srclen - -in -ttodata - -must not include the terminating NUL. -

- -Unless -dstlen - -is zero, -the result supplied by -datatot - -is always NUL-terminated, -and its needed-size return value includes space for the terminating NUL. -

- -Several obsolete variants of these functions -(atodata, - -datatoa, - -atobytes, - -and -bytestoa) - -are temporarily also supported. -  -

SEE ALSO

- -sprintf(3), ipsec_atoaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttodata - -and -ttodatav - -are: -unknown characters in the input; -unknown or missing prefix; -unknown base; -incomplete digit group; -non-zero padding in a base64 less-than-three-bytes digit group; -zero-length input. -

- -Fatal errors in -datatot - -are: -unknown format code; -zero-length input. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Datatot - -should have a format code to produce character-text output. -

- -The -0s - -and -0t - -prefixes are the author's inventions and are not a standard -of any kind. -They have been chosen to avoid collisions with existing practice -(some C implementations use -0b - -for binary) -and possible confusion with unprefixed hexadecimal. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_eroute.5.html b/doc/manpage.d/ipsec_eroute.5.html deleted file mode 100644 index 158b57015..000000000 --- a/doc/manpage.d/ipsec_eroute.5.html +++ /dev/null @@ -1,370 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_EROUTE - -

IPSEC_EROUTE

-Section: File Formats (5)
Updated: 20 Sep 2001
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_eroute - list of existing eroutes -  -

SYNOPSIS

- -ipsec - -eroute - -

- -cat - -/proc/net/ipsec_eroute - -  -

DESCRIPTION

- -/proc/net/ipsec_eroute - -lists the IPSEC extended routing tables, -which control what (if any) processing is applied -to non-encrypted packets arriving for IPSEC processing and forwarding. -At this point it is a read-only file. -

- -A table entry consists of: -

-
+
-packet count, -
+
-source address with mask, -
+
-a '->' separator for visual and automated parsing between src and dst -
+
-destination address with mask -
+
-a '=>' separator for visual and automated parsing between selection -criteria and SAID to use -
+
-SAID (Security Association IDentifier), comprised of: -
+
-protocol -(proto), -
+
-address family -(af), -where '.' stands for IPv4 and ':' for IPv6 -
+
-Security Parameters Index -(SPI), -
+
-effective destination -(edst), -where the packet should be forwarded after processing -(normally the other security gateway) -together indicate which Security Association should be used to process -the packet, -
+
-source identity text string with no whitespace, in parens, -
+
-destination identity text string with no whitespace, in parens -
-

- -Addresses are written as IPv4 dotted quads or IPv6 coloned hex, -protocol is one of "ah", "esp", "comp" or "tun" -and -SPIs are prefixed hexadecimal numbers where the prefix '.' is for IPv4 and the prefix ':' is for IPv6 -

- -SAIDs are written as "protoafSPI@edst". There are also 5 -"magic" SAIDs which have special meaning: -

-
+
-%drop - -means that matches are to be dropped -
+
-%reject - -means that matches are to be dropped and an ICMP returned, if -possible to inform -
+
-%trap - -means that matches are to trigger an ACQUIRE message to the Key -Management daemon(s) and a hold eroute will be put in place to -prevent subsequent packets also triggering ACQUIRE messages. -
+
-%hold - -means that matches are to stored until the eroute is replaced or -until that eroute gets reaped -
+
-%pass - -means that matches are to allowed to pass without IPSEC processing -
- - -
-  -

EXAMPLES

- -

- -1867 172.31.252.0/24 -> 0.0.0.0/0 => tun.130@192.168.43.1 - -
- - ()    () - -

- -means that 1,867 packets have been sent to an
-eroute - -that has been set up to protect traffic between the subnet -172.31.252.0 - -with a subnet mask of -24 - -bits and the default address/mask represented by an address of -0.0.0.0 - -with a subnet mask of -0 - -bits using the local machine as a security gateway on this end of the -tunnel and the machine -192.168.43.1 - -on the other end of the tunnel with a Security Association IDentifier of -tun0x130@192.168.43.1 - -which means that it is a tunnel mode connection (4, IPPROTO_IPIP) with a -Security Parameters Index of -130 - -in hexadecimal with no identies defined for either end. -

- -125 3049:1::/64 -> 0:0/0 => tun:130@3058:4::5 ()      () - -

- -means that 125 packets have been sent to an
-eroute - -that has been set up to protect traffic between the subnet -3049:1:: - -with a subnet mask of -64 - -bits and the default address/mask represented by an address of -0:0 - -with a subnet mask of -0 - -bits using the local machine as a security gateway on this end of the -tunnel and the machine -3058:4::5 - -on the other end of the tunnel with a Security Association IDentifier of -tun:130@3058:4::5 - -which means that it is a tunnel mode connection with a -Security Parameters Index of -130 - -in hexadecimal with no identies defined for either end. -

- -42 192.168.6.0/24 -> 192.168.7.0/24 => %passthrough - -

- -means that 42 packets have been sent to an -eroute - -that has been set up to pass the traffic from the subnet -192.168.6.0 - -with a subnet mask of -24 - -bits and to subnet -192.168.7.0 - -with a subnet mask of -24 - -bits without any IPSEC processing with no identies defined for either end. -

- -2112 192.168.8.55/32 -> 192.168.9.47/24 => %hold     (east)  () - -

- -means that 2112 packets have been sent to an
-eroute - -that has been set up to hold the traffic from the host -192.168.8.55 - -and to host -192.168.9.47 - -until a key exchange from a Key Management daemon -succeeds and puts in an SA or fails and puts in a pass -or drop eroute depending on the default configuration with the local client -defined as "east" and no identy defined for the remote end. -

- -2001 192.168.2.110/32 -> 192.168.2.120/32 => - -
- - esp.e6de@192.168.2.120        ()      () - -

- -means that 2001 packets have been sent to an
-eroute - -that has been set up to protect traffic between the host -192.168.2.110 - -and the host -192.168.2.120 - -using -192.168.2.110 - -as a security gateway on this end of the -connection and the machine -192.168.2.120 - -on the other end of the connection with a Security Association IDentifier of -esp.e6de@192.168.2.120 - -which means that it is a transport mode connection with a Security -Parameters Index of -e6de - -in hexadecimal using Encapsuation Security Payload protocol (50, -IPPROTO_ESP) with no identies defined for either end. -

- -1984 3049:1::110/128 -> 3049:1::120/128 => - -
- - ah:f5ed@3049:1::120   ()      () - -

- -means that 1984 packets have been sent to an
-eroute - -that has been set up to authenticate traffic between the host -3049:1::110 - -and the host -3049:1::120 - -using -3049:1::110 - -as a security gateway on this end of the -connection and the machine -3049:1::120 - -on the other end of the connection with a Security Association IDentifier of -ah:f5ed@3049:1::120 - -which means that it is a transport mode connection with a Security -Parameters Index of -f5ed - -in hexadecimal using Authentication Header protocol (51, -IPPROTO_AH) with no identies defined for either end. -  -

FILES

- -/proc/net/ipsec_eroute, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(5), ipsec_spi(5), -ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_eroute(8), ipsec_version(5), -ipsec_pf_key(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_eroute.8.html b/doc/manpage.d/ipsec_eroute.8.html deleted file mode 100644 index 7489462d7..000000000 --- a/doc/manpage.d/ipsec_eroute.8.html +++ /dev/null @@ -1,421 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_EROUTE - -

IPSEC_EROUTE

-Section: Maintenance Commands (8)
Updated: 21 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec eroute - manipulate IPSEC extended routing tables -  -

SYNOPSIS

- -ipsec - -eroute - -

- -ipsec - -eroute - ---add - ---eraf (inet | inet6) - ---src - -src/srcmaskbits|srcmask ---dst - -dst/dstmaskbits|dstmask -<SAID> -

- -ipsec - -eroute - ---replace - ---eraf (inet | inet6) - ---src - -src/srcmaskbits|srcmask ---dst - -dst/dstmaskbits|dstmask -<SAID> -

- -ipsec - -eroute - ---del - ---eraf (inet | inet6) - ---src - -src/srcmaskbits|srcmask ---dst - -dst/dstmaskbits|dstmask -

- -ipsec - -eroute - ---clear - -

- -ipsec - -eroute - ---help - -

- -ipsec - -eroute - ---version - -

- -Where <SAID> is ---af - -(inet | inet6) ---edst - -edst ---spi - -spi ---proto - -proto -OR ---said - -said -OR ---said - -(%passthrough | %passthrough4 | %passthrough6) - -  -

DESCRIPTION

- -Eroute - -manages the IPSEC extended routing tables, -which control what (if any) processing is applied -to non-encrypted packets arriving for IPSEC processing and forwarding. -The form with no additional arguments lists the contents of -/proc/net/ipsec_eroute. -The ---add - -form adds a table entry, the ---replace - -form replaces a table entry, while the ---del - -form deletes one. The ---clear - -form deletes the entire table. -

- -A table entry consists of: -

-
+
-source and destination addresses, -with masks, -for selection of packets -
+
-Security Association IDentifier, comprised of: -
+
-protocol -(proto), indicating (together with the -effective destination and the security parameters index) -which Security Association should be used to process the packet -
+
-address family -(af), -
+
-Security Parameters Index -(spi), indicating (together with the -effective destination and protocol) -which Security Association should be used to process the packet -(must be larger than or equal to 0x100) -
+
-effective destination -(edst), -where the packet should be forwarded after processing -(normally the other security gateway) -
+
-OR -
+
-SAID -(said), indicating -which Security Association should be used to process the packet -
-

- -Addresses are written as IPv4 dotted quads or IPv6 coloned hex, -protocol is one of "ah", "esp", "comp" or "tun" and SPIs are -prefixed hexadecimal numbers where '.' represents IPv4 and ':' -stands for IPv6. -

- -SAIDs are written as "protoafSPI@address". There are also 5 -"magic" SAIDs which have special meaning: -

-
+
-%drop - -means that matches are to be dropped -
+
-%reject - -means that matches are to be dropped and an ICMP returned, if -possible to inform -
+
-%trap - -means that matches are to trigger an ACQUIRE message to the Key -Management daemon(s) and a hold eroute will be put in place to -prevent subsequent packets also triggering ACQUIRE messages. -
+
-%hold - -means that matches are to stored until the eroute is replaced or -until that eroute gets reaped -
+
-%pass - -means that matches are to allowed to pass without IPSEC processing -
-

- -The format of /proc/net/ipsec_eroute is listed in ipsec_eroute(5). -
- - -  -

EXAMPLES

- -

- -ipsec eroute --add --eraf inet --src 192.168.0.1/32 \ - -
- - --dst 192.168.2.0/24 --af inet --edst 192.168.0.2 \ - -
- - --spi 0x135 --proto tun - -

- -sets up an -eroute - -on a Security Gateway to protect traffic between the host -192.168.0.1 - -and the subnet -192.168.2.0 - -with -24 - -bits of subnet mask via Security Gateway -192.168.0.2 - -using the Security Association with address -192.168.0.2, - -Security Parameters Index -0x135 - -and protocol -tun - -(50, IPPROTO_ESP). -

- -ipsec eroute --add --eraf inet6 --src 3049:1::1/128 \ - -
- - --dst 3049:2::/64 --af inet6 --edst 3049:1::2 \ - -
- - --spi 0x145 --proto tun - -

- -sets up an -eroute - -on a Security Gateway to protect traffic between the host -3049:1::1 - -and the subnet -3049:2:: - -with -64 - -bits of subnet mask via Security Gateway -3049:1::2 - -using the Security Association with address -3049:1::2, - -Security Parameters Index -0x145 - -and protocol -tun - -(50, IPPROTO_ESP). -

- -ipsec eroute --replace --eraf inet --src company.com/24 \ - -
- - --dst ftp.ngo.org/32 --said tun.135@gw.ngo.org - -

- -replaces an -eroute - -on a Security Gateway to protect traffic between the subnet -company.com - -with -24 - -bits of subnet mask and the host -ftp.ngo.org - -via Security Gateway -gw.ngo.org - -using the Security Association with Security Association ID -tun0x135@gw.ngo.org - -

- -ipsec eroute --del --eraf inet --src company.com/24 \ - -
- - --dst www.ietf.org/32 --said %passthrough4 - -

- -deletes an -eroute - -on a Security Gateway that allowed traffic between the subnet -company.com - -with -24 - -bits of subnet mask and the host -www.ietf.org - -to pass in the clear, unprocessed. -  -

FILES

- -/proc/net/ipsec_eroute, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_spi(8), -ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_eroute(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_goodmask.3.html b/doc/manpage.d/ipsec_goodmask.3.html deleted file mode 100644 index a67a08d83..000000000 --- a/doc/manpage.d/ipsec_goodmask.3.html +++ /dev/null @@ -1,122 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_GOODMASK - -

IPSEC_GOODMASK

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec goodmask - is this Internet subnet mask a valid one? -
- -ipsec masktobits - convert Internet subnet mask to bit count -
- -ipsec bitstomask - convert bit count to Internet subnet mask -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int goodmask(struct in_addr mask); - -
- -int masktobits(struct in_addr mask); - -
- -struct in_addr bitstomask(int n); - -  -

DESCRIPTION

- -These functions are obsolete; -see -ipsec_masktocount(3) - -for a partial replacement. -

- -Goodmask - -reports whether the subnet -mask - -is a valid one, -i.e. consists of a (possibly empty) sequence of -1s - -followed by a (possibly empty) sequence of -0s. - -Masktobits - -takes a (valid) subnet mask and returns the number of -1 - -bits in it. -Bitstomask - -reverses this, -returning the subnet mask corresponding to bit count -n. - -

- -All masks are in network byte order. -  -

SEE ALSO

- -inet(3), ipsec_atosubnet(3) -  -

DIAGNOSTICS

- -Masktobits - -returns --1 - -for an invalid mask. -Bitstomask - -returns an all-zeros mask for a negative or out-of-range -n. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The error-reporting convention of -bitstomask - -is less than ideal; -zero is sometimes a legitimate mask. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_hostof.3.html b/doc/manpage.d/ipsec_hostof.3.html deleted file mode 100644 index 57d4a5648..000000000 --- a/doc/manpage.d/ipsec_hostof.3.html +++ /dev/null @@ -1,107 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SUBNETOF - -

IPSEC_SUBNETOF

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec subnetof - given Internet address and subnet mask, return subnet number -
- -ipsec hostof - given Internet address and subnet mask, return host part -
- -ipsec broadcastof - given Internet address and subnet mask, return broadcast address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-struct in_addr subnetof(struct in_addr addr, - -
-  -struct in_addr mask); - -
- -struct in_addr hostof(struct in_addr addr, - -
-  -struct in_addr mask); - -
- -struct in_addr broadcastof(struct in_addr addr, - -
-  -struct in_addr mask); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_networkof(3) - -for their replacements. -

- -Subnetof - -takes an Internet -address - -and a subnet -mask - -and returns the network part of the address -(all in network byte order). -Hostof - -similarly returns the host part, and -broadcastof - -returns the broadcast address (all-1s convention) for the network. -

- -These functions are provided to hide the Internet bit-munging inside -an API, in hopes of easing the eventual transition to IPv6. -  -

SEE ALSO

- -inet(3), ipsec_atosubnet(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Calling functions for this is more costly than doing it yourself. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ikeping.8.html b/doc/manpage.d/ipsec_ikeping.8.html deleted file mode 100644 index 03ed961f3..000000000 --- a/doc/manpage.d/ipsec_ikeping.8.html +++ /dev/null @@ -1,137 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_IKEPING - -

IPSEC_IKEPING

-Section: Maintenance Commands (8)
Updated: 23 Feb 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ikeping - send/receive ISAKMP/IKE echo requests/replies -  -

SYNOPSIS

- -ipsec - -ikeping - -[ ---listen - -] [ ---verbose - -] [ ---wait - -time ] [ ---exchangenum - -num ] [ ---ikeport - -localport ] [ ---ikeaddress - -address ] [ ---inet - -] [ ---inet6 - -] destaddr[/dstport] ... -  -

DESCRIPTION

- -Ikeping - -sends and receives ISAKMP/IKE echo request and echo reply packets. These -packets are intended for diagnostics purposes, in a manner similar to -ping(8) - -does for ICMP echo request/reply packets. -

- -At the time of this writing, the ISAKMP echo request/reply exchange is still -an internet-draft, and is therefore completely non-standard. -

- -Ikeping - -will bind to the local address given by ---ikeaddress - -and the port number given by ---ikeport - -defaulting to the wildcard address and the ISAKMP port 500. An ISAKMP -exchange of type 244 (a private use number) is sent to each of the -address/ports listed on the command line. The exchange number may be -overridden by the ---exchangenum - -option. -

- -Ikeping - -then listens for replies, printing them as they are received. Replies -are of exchange type 245 or the specified exchange number plus 1. -Ikeping - -will keep listening until it either receives as many echo responses as it sent, -or until the timeout period (10 seconds) has been reached. Receipt of a -packet will reset the timer. The ---wait - -option can be used to specify a different timeout period. -

- -If the ---listen - -option is given, then -ikeping - -will not send any packets. Instead, it will listen for them and reply to -each request received. -  -

FILES

- -no external files -  -

SEE ALSO

- -ping(8), ipsec_pluto(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Michael Richardson. -  -

BUGS

- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_initaddr.3.html b/doc/manpage.d/ipsec_initaddr.3.html deleted file mode 100644 index ca1f857e7..000000000 --- a/doc/manpage.d/ipsec_initaddr.3.html +++ /dev/null @@ -1,232 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITADDR - -

IPSEC_INITADDR

-Section: C Library Functions (3)
Updated: 11 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initaddr - initialize an ip_address -
- -ipsec addrtypeof - get address type of an ip_address -
- -ipsec addrlenof - get length of address within an ip_address -
- -ipsec addrbytesof - get copy of address within an ip_address -
- -ipsec addrbytesptr - get pointer to address within an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *dst); - -
- -int addrtypeof(const ip_address *src); - -
- -size_t addrlenof(const ip_address *src); - -
- -size_t addrbytesof(const ip_address *src, - -
-  -unsigned char *dst, size_t dstlen); - -
- -size_t addrbytesptr(const ip_address *src, - -
-  -const unsigned char **dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_address - -to contain one of the (currently two) types of IP address. -These functions provide basic tools for creating and examining this type. -

- -Initaddr - -initializes a variable -*dst - -of type -ip_address - -from an address -(in network byte order, -indicated by a pointer -src - -and a length -srclen) - -and an address family -af - -(typically -AF_INET - -or -AF_INET6). - -The length must be consistent with the address family. -

- -Addrtypeof - -returns the address type of an address, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Addrlenof - -returns the size (in bytes) of the address within an -ip_address, - -to permit storage allocation etc. -

- -Addrbytesof - -copies the address within the -ip_address - -src - -to the buffer indicated by the pointer -dst - -and the length -dstlen, - -and returns the address length (in bytes). -If the address will not fit, -as many bytes as will fit are copied; -the returned length is still the full length. -It is the caller's responsibility to check the -returned value to ensure that there was enough room. -

- -Addrbytesptr - -sets -*dst - -to a pointer to the internal address within the -ip_address, - -and returns the address length (in bytes). -If -dst - -is -NULL, - -it just returns the address length. -The pointer points to -const - -to discourage misuse. -

- -Initaddr - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -The functions which return -size_t - -return -0 - -for a failure. -  -

SEE ALSO

- -inet(3), ipsec_ttoaddr(3) -  -

DIAGNOSTICS

- -An unknown address family is a fatal error for any of these functions -except -addrtypeof. - -An address-size mismatch is a fatal error for -initaddr. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Addrtypeof - -should probably have been named -addrfamilyof. - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_initsaid.3.html b/doc/manpage.d/ipsec_initsaid.3.html deleted file mode 100644 index 2ba79a8ac..000000000 --- a/doc/manpage.d/ipsec_initsaid.3.html +++ /dev/null @@ -1,453 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOSA - -

IPSEC_TTOSA

-Section: C Library Functions (3)
Updated: 26 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttosa, satot - convert IPsec Security Association IDs to and from text -
- -ipsec initsaid - initialize an SA ID -  -

SYNOPSIS

- -#include <freeswan.h> - -

-typedef struct { - -
-  -ip_address dst; - -
-  -ipsec_spi_t spi; - -
-  -int proto; - -
- -} ip_said; - -

-const char *ttosa(const char *src, size_t srclen, - -
-  -ip_said *sa); - -
- -size_t satot(const ip_said *sa, int format, - -
-  -char *dst, size_t dstlen); - -
- -void initsaid(const ip_address *addr, ipsec_spi_t spi, - -
-  -int proto, ip_said *dst); - -  -

DESCRIPTION

- -Ttosa - -converts an ASCII Security Association (SA) specifier into an -ip_said - -structure (containing -a destination-host address -in network byte order, -an SPI number in network byte order, and -a protocol code). -Satot - -does the reverse conversion, back to a text SA specifier. -Initsaid - -initializes an -ip_said - -from separate items of information. -

- -An SA is specified in text with a mail-like syntax, e.g. -esp.5a7@1.2.3.4. - -An SA specifier contains -a protocol prefix (currently -ah, - -esp, - -tun, - -comp, - -or -int), - -a single character indicating the address family -(. - -for IPv4, -: - -for IPv6), -an unsigned integer SPI number in hexadecimal (with no -0x - -prefix), -and an IP address. -The IP address can be any form accepted by -ipsec_ttoaddr(3), - -e.g. dotted-decimal IPv4 address, -colon-hex IPv6 address, -or DNS name. -

- -As a special case, the SA specifier -%passthrough4 - -or -%passthrough6 - -signifies the special SA used to indicate that packets should be -passed through unaltered. -(At present, these are synonyms for -tun.0@0.0.0.0 - -and -tun:0@:: - -respectively, -but that is subject to change without notice.) -%passthrough - -is a historical synonym for -%passthrough4. - -These forms are known to both -ttosa - -and -satot, - -so the internal representation is never visible. -

- -Similarly, the SA specifiers -%pass, - -%drop, - -%reject, - -%hold, - -%trap, - -and -%trapsubnet - -signify special ``magic'' SAs used to indicate that packets should be -passed, dropped, rejected (dropped with ICMP notification), -held, -and trapped (sent up to -ipsec_pluto(8), - -with either of two forms of -%hold - -automatically installed) -respectively. -These forms too are known to both routines, -so the internal representation of the magic SAs should never be visible. -

- -The -<freeswan.h> - -header file supplies the -ip_said - -structure, as well as a data type -ipsec_spi_t - -which is an unsigned 32-bit integer. -(There is no consistency between kernel and user on what such a type -is called, hence the header hides the differences.) -

- -The protocol code uses the same numbers that IP does. -For user convenience, given the difficulty in acquiring the exact set of -protocol names used by the kernel, -<freeswan.h> - -defines the names -SA_ESP, - -SA_AH, - -SA_IPIP, - -and -SA_COMP - -to have the same values as the kernel names -IPPROTO_ESP, - -IPPROTO_AH, - -IPPROTO_IPIP, - -and -IPPROTO_COMP. - -

- -<freeswan.h> - -also defines -SA_INT - -to have the value -61 - -(reserved by IANA for ``any host internal protocol'') -and -SPI_PASS, - -SPI_DROP, - -SPI_REJECT, - -SPI_HOLD, - -and -SPI_TRAP - -to have the values 256-260 (in host byte order) respectively. -These are used in constructing the magic SAs -(which always have address -0.0.0.0). - -

- -If -satot - -encounters an unknown protocol code, e.g. 77, -it yields output using a prefix -showing the code numerically, e.g. ``unk77''. -This form is -not - -recognized by -ttosa. - -

- -The -srclen - -parameter of -ttosa - -specifies the length of the string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -satot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -<freeswan.h> - -header file defines a constant, -SATOT_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -satot - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default -(currently -lowercase protocol prefix, lowercase hexadecimal SPI, -dotted-decimal or colon-hex address). -The value -'f' - -is similar except that the SPI is padded with -0s - -to a fixed 32-bit width, to ease aligning displayed tables. -

- -Ttosa - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Satot - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -

- -There is also, temporarily, support for some obsolete -forms of SA specifier which lack the address-family indicator. -  -

SEE ALSO

- -ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttosa - -are: -empty input; -input too small to be a legal SA specifier; -no -@ - -in input; -unknown protocol prefix; -conversion error in -ttoul - -or -ttoaddr. - -

- -Fatal errors in -satot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttosa( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_initsubnet.3.html b/doc/manpage.d/ipsec_initsubnet.3.html deleted file mode 100644 index e442a9100..000000000 --- a/doc/manpage.d/ipsec_initsubnet.3.html +++ /dev/null @@ -1,238 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITSUBNET - -

IPSEC_INITSUBNET

-Section: C Library Functions (3)
Updated: 12 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initsubnet - initialize an ip_subnet -
- -ipsec addrtosubnet - initialize a singleton ip_subnet -
- -ipsec subnettypeof - get address type of an ip_subnet -
- -ipsec masktocount - convert subnet mask to bit count -
- -ipsec networkof - get base address of an ip_subnet -
- -ipsec maskof - get subnet mask of an ip_subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initsubnet(const ip_address *addr, - -
-  -int maskbits, int clash, ip_subnet *dst); - -
- -const char *addrtosubnet(const ip_address *addr, - -
-  -ip_subnet *dst); - -

-int subnettypeof(const ip_subnet *src); - -
- -int masktocount(const ip_address *src); - -
- -void networkof(const ip_subnet *src, ip_address *dst); - -
- -void maskof(const ip_subnet *src, ip_address *dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_subnet - -to contain a description of an IP subnet -(base address plus mask). -These functions provide basic tools for creating and examining this type. -

- -Initsubnet - -initializes a variable -*dst - -of type -ip_subnet - -from a base address and -a count of mask bits. -The -clash - -parameter specifies what to do if the base address includes -1 - -bits outside the prefix specified by the mask -(that is, in the ``host number'' part of the address): -

-
-
'0'
-zero out host-number bits -
'x'
-non-zero host-number bits are an error -
-
- -

- -Initsubnet - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -Addrtosubnet - -initializes an -ip_subnet - -variable -*dst - -to a ``singleton subnet'' containing the single address -*addr. - -It returns -NULL - -for success and -a pointer to a string-literal error message for failure. -

- -Subnettypeof - -returns the address type of a subnet, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Masktocount - -converts a subnet mask, expressed as an address, to a bit count -suitable for use with -initsubnet. - -It returns --1 - -for error; see DIAGNOSTICS. -

- -Networkof - -fills in -*dst - -with the base address of subnet -src. - -

- -Maskof - -fills in -*dst - -with the subnet mask of subnet -src, - -expressed as an address. -  -

SEE ALSO

- -inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -initsubnet - -are: -unknown address family; -unknown -clash - -value; -impossible mask bit count; -non-zero host-number bits and -clash - -is -'x'. - -Fatal errors in -addrtosubnet - -are: -unknown address family. -Fatal errors in -masktocount - -are: -unknown address family; -mask bits not contiguous. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_isanyaddr.3.html b/doc/manpage.d/ipsec_isanyaddr.3.html deleted file mode 100644 index 974236005..000000000 --- a/doc/manpage.d/ipsec_isanyaddr.3.html +++ /dev/null @@ -1,166 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec anyaddr - get "any" address -
- -ipsec isanyaddr - test address for equality to "any" address -
- -ipsec unspecaddr - get "unspecified" address -
- -ipsec isunspecaddr - test address for equality to "unspecified" address -
- -ipsec loopbackaddr - get loopback address -
- -ipsec isloopbackaddr - test address for equality to loopback address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *anyaddr(int af, ip_address *dst); - -
- -int isanyaddr(const ip_address *src); - -
- -const char *unspecaddr(int af, ip_address *dst); - -
- -int isunspecaddr(const ip_address *src); - -
- -const char *loopbackaddr(int af, ip_address *dst); - -
- -int isloopbackaddr(const ip_address *src); - -  -

DESCRIPTION

- -These functions fill in, and test for, special values of the -ip_address - -type. -

- -Anyaddr - -fills in the destination -*dst - -with the ``any'' address of address family -af - -(normally -AF_INET - -or -AF_INET6). - -The IPv4 ``any'' address is the one embodied in the old -INADDR_ANY - -macro. -

- -Isanyaddr - -returns -1 - -if the -src - -address equals the ``any'' address, -and -0 - -otherwise. -

- -Similarly, -unspecaddr - -supplies, and -isunspecaddr - -tests for, -the ``unspecified'' address, -which may be the same as the ``any'' address. -

- -Similarly, -loopbackaddr - -supplies, and -islookbackaddr - -tests for, -the loopback address. -

- -Anyaddr, - -unspecaddr, - -and -loopbackaddr - -return -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -inet(3), ipsec_addrtot(3), ipsec_sameaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in the address-supplying functions are: -unknown address family. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_isloopbackaddr.3.html b/doc/manpage.d/ipsec_isloopbackaddr.3.html deleted file mode 100644 index 974236005..000000000 --- a/doc/manpage.d/ipsec_isloopbackaddr.3.html +++ /dev/null @@ -1,166 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec anyaddr - get "any" address -
- -ipsec isanyaddr - test address for equality to "any" address -
- -ipsec unspecaddr - get "unspecified" address -
- -ipsec isunspecaddr - test address for equality to "unspecified" address -
- -ipsec loopbackaddr - get loopback address -
- -ipsec isloopbackaddr - test address for equality to loopback address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *anyaddr(int af, ip_address *dst); - -
- -int isanyaddr(const ip_address *src); - -
- -const char *unspecaddr(int af, ip_address *dst); - -
- -int isunspecaddr(const ip_address *src); - -
- -const char *loopbackaddr(int af, ip_address *dst); - -
- -int isloopbackaddr(const ip_address *src); - -  -

DESCRIPTION

- -These functions fill in, and test for, special values of the -ip_address - -type. -

- -Anyaddr - -fills in the destination -*dst - -with the ``any'' address of address family -af - -(normally -AF_INET - -or -AF_INET6). - -The IPv4 ``any'' address is the one embodied in the old -INADDR_ANY - -macro. -

- -Isanyaddr - -returns -1 - -if the -src - -address equals the ``any'' address, -and -0 - -otherwise. -

- -Similarly, -unspecaddr - -supplies, and -isunspecaddr - -tests for, -the ``unspecified'' address, -which may be the same as the ``any'' address. -

- -Similarly, -loopbackaddr - -supplies, and -islookbackaddr - -tests for, -the loopback address. -

- -Anyaddr, - -unspecaddr, - -and -loopbackaddr - -return -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -inet(3), ipsec_addrtot(3), ipsec_sameaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in the address-supplying functions are: -unknown address family. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_isunspecaddr.3.html b/doc/manpage.d/ipsec_isunspecaddr.3.html deleted file mode 100644 index 974236005..000000000 --- a/doc/manpage.d/ipsec_isunspecaddr.3.html +++ /dev/null @@ -1,166 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec anyaddr - get "any" address -
- -ipsec isanyaddr - test address for equality to "any" address -
- -ipsec unspecaddr - get "unspecified" address -
- -ipsec isunspecaddr - test address for equality to "unspecified" address -
- -ipsec loopbackaddr - get loopback address -
- -ipsec isloopbackaddr - test address for equality to loopback address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *anyaddr(int af, ip_address *dst); - -
- -int isanyaddr(const ip_address *src); - -
- -const char *unspecaddr(int af, ip_address *dst); - -
- -int isunspecaddr(const ip_address *src); - -
- -const char *loopbackaddr(int af, ip_address *dst); - -
- -int isloopbackaddr(const ip_address *src); - -  -

DESCRIPTION

- -These functions fill in, and test for, special values of the -ip_address - -type. -

- -Anyaddr - -fills in the destination -*dst - -with the ``any'' address of address family -af - -(normally -AF_INET - -or -AF_INET6). - -The IPv4 ``any'' address is the one embodied in the old -INADDR_ANY - -macro. -

- -Isanyaddr - -returns -1 - -if the -src - -address equals the ``any'' address, -and -0 - -otherwise. -

- -Similarly, -unspecaddr - -supplies, and -isunspecaddr - -tests for, -the ``unspecified'' address, -which may be the same as the ``any'' address. -

- -Similarly, -loopbackaddr - -supplies, and -islookbackaddr - -tests for, -the loopback address. -

- -Anyaddr, - -unspecaddr, - -and -loopbackaddr - -return -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -inet(3), ipsec_addrtot(3), ipsec_sameaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in the address-supplying functions are: -unknown address family. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:17 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_keyblobtoid.3.html b/doc/manpage.d/ipsec_keyblobtoid.3.html deleted file mode 100644 index 109cfafa7..000000000 --- a/doc/manpage.d/ipsec_keyblobtoid.3.html +++ /dev/null @@ -1,174 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_KEYBLOBTOID - -

IPSEC_KEYBLOBTOID

-Section: C Library Functions (3)
Updated: 25 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec keyblobtoid, splitkeytoid - generate key IDs from RSA keys -  -

SYNOPSIS

- -#include <freeswan.h> - -

-size_t keyblobtoid(const unsigned char *blob, - -
-  -size_t bloblen, char *dst, size_t dstlen); - -
- -size_t splitkeytoid(const unsigned char *e, size_t elen, - -
-  -const unsigned char *m, size_t mlen, char *dst, - -
-  -size_t dstlen); - -  -

DESCRIPTION

- -Keyblobtoid - -and -splitkeytoid - -generate -key IDs -from RSA keys, -for use in messages and reporting, -writing the result to -dst. - -A -key ID - -is a short ASCII string identifying a key; -currently it is just the first nine characters of the base64 -encoding of the RFC 2537/3110 ``byte blob'' representation of the key. -(Beware that no finite key ID can be collision-proof: -there is always some small chance of two random keys having the -same ID.) -

- -Keyblobtoid - -generates a key ID from a key which is already in the form of an -RFC 2537/3110 binary key -blob - -(encoded exponent length, exponent, modulus). -

- -Splitkeytoid - -generates a key ID from a key given in the form of a separate -(binary) exponent -e - -and modulus -m. - -

- -The -dstlen - -parameter of either -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant -KEYID_BUF - -which is the size of a buffer large enough for worst-case results. -

- -Both functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. - -With keys generated by -ipsec_rsasigkey(3), - -the first two base64 digits are always the same, -and the third carries only about one bit of information. -It's worse with keys using longer fixed exponents, -e.g. the 24-bit exponent that's common in X.509 certificates. -However, being able to relate key IDs to the full -base64 text form of keys by eye is sufficiently useful that this -waste of space seems justifiable. -The choice of nine digits is a compromise between bulk and -probability of collision. -  -

SEE ALSO

- -RFC 3110, -RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS), -Eastlake, 2001 -(superseding the older but better-known RFC 2537). -  -

DIAGNOSTICS

- -Fatal errors are: -key too short to supply enough bits to construct a complete key ID -(almost certainly indicating a garbage key); -exponent too long for its length to be representable. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_klipsdebug.5.html b/doc/manpage.d/ipsec_klipsdebug.5.html deleted file mode 100644 index 964329256..000000000 --- a/doc/manpage.d/ipsec_klipsdebug.5.html +++ /dev/null @@ -1,229 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_KLIPSDEBUG - -

IPSEC_KLIPSDEBUG

-Section: File Formats (5)
Updated: 26 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_klipsdebug - list KLIPS (kernel IPSEC support) debug features and level -  -

SYNOPSIS

- -ipsec - -klipsdebug - -

- -cat - -/proc/net/ipsec_klipsdebug - -  -

DESCRIPTION

- -/proc/net/ipsec_klipsdebug - -lists flags that control various parts of the debugging output of Klips -(the kernel portion of FreeS/WAN IPSEC). -At this point it is a read-only file. -

- -A table entry consists of: -

-
+
-a KLIPS debug variable -
+
-a '=' separator for visual and automated parsing between the variable -name and its current value -
+
-hexadecimal bitmap of variable's flags. -
-

- -The variable names roughly describe the scope of the debugging variable. -Currently, no flags are documented or individually accessible yet except -tunnel-xmit. - -

- -The variable names are: -

-
tunnel - -
-tunnelling code -
netlink - -
-userspace communication code (obsolete) -
xform - -
-transform selection and manipulation code -
eroute - -
-eroute table manipulation code -
spi - -
-SA table manipulation code -
radij - -
-radij tree manipulation code -
esp - -
-encryptions transforms code -
ah - -
-authentication transforms code -
rcv - -
-receive code -
ipcomp - -
-ip compression transforms code -
verbose - -
-give even more information, beware this will probably trample the 4k kernel printk buffer giving inaccurate output -
-

- -All KLIPS debug output appears as -kernel.info - -messages to -syslogd(8). - -Most systems are set up -to log these messages to -/var/log/messages. - -

- -  -

EXAMPLES

- -

- -debug_tunnel=00000010. - -
- -debug_netlink=00000000. - -
- -debug_xform=00000000. - -
- -debug_eroute=00000000. - -
- -debug_spi=00000000. - -
- -debug_radij=00000000. - -
- -debug_esp=00000000. - -
- -debug_ah=00000000. - -
- -debug_rcv=00000000. - -
- -debug_pfkey=ffffffff. - -

- -means that one -tunnel - -flag has been set (tunnel-xmit), -full -pfkey - -sockets debugging has been set and everything else is not set. -

- -  -

FILES

- -/proc/net/ipsec_klipsdebug, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8), -ipsec_spi(8), ipsec_spigrp(8), ipsec_klipsdebug(5), ipsec_version(5), -ipsec_pf_key(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_klipsdebug.8.html b/doc/manpage.d/ipsec_klipsdebug.8.html deleted file mode 100644 index 67b1c3a5d..000000000 --- a/doc/manpage.d/ipsec_klipsdebug.8.html +++ /dev/null @@ -1,264 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_KLIPSDEBUG - -

IPSEC_KLIPSDEBUG

-Section: Maintenance Commands (8)
Updated: 21 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec klipsdebug - set KLIPS (kernel IPSEC support) debug features and level -  -

SYNOPSIS

- -ipsec - -klipsdebug - -

- -ipsec - -klipsdebug - ---set - -flagname -

- -ipsec - -klipsdebug - ---clear - -flagname -

- -ipsec - -klipsdebug - ---all - -

- -ipsec - -klipsdebug - ---none - -

- -ipsec - -klipsdebug - ---help - -

- -ipsec - -klipsdebug - ---version - -  -

DESCRIPTION

- -Klipsdebug - -sets and clears flags that control -various parts of the debugging output of Klips -(the kernel portion of FreeS/WAN IPSEC). -The form with no additional arguments lists the present contents of -/proc/net/ipsec_klipsdebug. -The ---set - -form turns the specified flag on, -while the ---clear - -form turns the specified flag off. -The ---all - -form -turns all flags on except verbose, while the ---none - -form turns all flags off. -

- -The current flag names are: -

-
tunnel - -
-tunnelling code -
tunnel-xmit - -
-tunnelling transmit only code -
pfkey - -
-userspace communication code -
xform - -
-transform selection and manipulation code -
eroute - -
-eroute table manipulation code -
spi - -
-SA table manipulation code -
radij - -
-radij tree manipulation code -
esp - -
-encryptions transforms code -
ah - -
-authentication transforms code -rcv - -receive code -
ipcomp - -
-ip compression transforms code -
verbose - -
-give even more information, BEWARE: -a)this will print authentication and encryption keys in the logs -b)this will probably trample the 4k kernel printk buffer giving inaccurate output -
-

- -All Klips debug output appears as -kernel.info - -messages to -syslogd(8). - -Most systems are set up -to log these messages to -/var/log/messages. - -Beware that -klipsdebug - ---all - -produces a lot of output and the log file will grow quickly. -

- -The file format for /proc/net/ipsec_klipsdebug is discussed in -ipsec_klipsdebug(5). -  -

EXAMPLES

- -
-
klipsdebug --all - -
-turns on all KLIPS debugging except verbose. -
klipsdebug --clear tunnel - -
-turns off only the -tunnel - -debugging messages. -
-

- -  -

FILES

- -/proc/net/ipsec_klipsdebug, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8), -ipsec_spi(8), ipsec_spigrp(8), ipsec_klipsdebug(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. -  -

BUGS

- -It really ought to be possible to set or unset selective combinations -of flags. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_look.8.html b/doc/manpage.d/ipsec_look.8.html deleted file mode 100644 index ffe07a57c..000000000 --- a/doc/manpage.d/ipsec_look.8.html +++ /dev/null @@ -1,76 +0,0 @@ -Content-type: text/html - -Manpage of look - -

look

-Section: Maintenance Commands (8)
Updated: 25 Apr 2002
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec look - get a quick summary of FreeS/WAN status -  -

SYNOPSIS

- -look - -is used to get a quick overview of what the status of FreeSWAN is. -It is equivalent to: -   ipsec eroute -

-   ipsec spigrp -

-   ipsec tncfg -

-   ipsec spi -

-   netstat -rn -

-

- -However a bit of processing is done to combine the outputs. -  -

SEE ALSO

- -ipsec(8), ipsec_tncfg(8), ipsec_spi(8), ipsec_spigrp(8), ipsec_eroute(5), -netstat(8). -  -

HISTORY

- -Man page written for the Linux FreeS/WAN project <http://www.freeswan.org/> -by Michael Richardson. Original program written by Henry Spencer. - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_loopbackaddr.3.html b/doc/manpage.d/ipsec_loopbackaddr.3.html deleted file mode 100644 index 92f69d99c..000000000 --- a/doc/manpage.d/ipsec_loopbackaddr.3.html +++ /dev/null @@ -1,166 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec anyaddr - get "any" address -
- -ipsec isanyaddr - test address for equality to "any" address -
- -ipsec unspecaddr - get "unspecified" address -
- -ipsec isunspecaddr - test address for equality to "unspecified" address -
- -ipsec loopbackaddr - get loopback address -
- -ipsec isloopbackaddr - test address for equality to loopback address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *anyaddr(int af, ip_address *dst); - -
- -int isanyaddr(const ip_address *src); - -
- -const char *unspecaddr(int af, ip_address *dst); - -
- -int isunspecaddr(const ip_address *src); - -
- -const char *loopbackaddr(int af, ip_address *dst); - -
- -int isloopbackaddr(const ip_address *src); - -  -

DESCRIPTION

- -These functions fill in, and test for, special values of the -ip_address - -type. -

- -Anyaddr - -fills in the destination -*dst - -with the ``any'' address of address family -af - -(normally -AF_INET - -or -AF_INET6). - -The IPv4 ``any'' address is the one embodied in the old -INADDR_ANY - -macro. -

- -Isanyaddr - -returns -1 - -if the -src - -address equals the ``any'' address, -and -0 - -otherwise. -

- -Similarly, -unspecaddr - -supplies, and -isunspecaddr - -tests for, -the ``unspecified'' address, -which may be the same as the ``any'' address. -

- -Similarly, -loopbackaddr - -supplies, and -islookbackaddr - -tests for, -the loopback address. -

- -Anyaddr, - -unspecaddr, - -and -loopbackaddr - -return -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -inet(3), ipsec_addrtot(3), ipsec_sameaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in the address-supplying functions are: -unknown address family. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_lwdnsq.8.html b/doc/manpage.d/ipsec_lwdnsq.8.html deleted file mode 100644 index 1122b188a..000000000 --- a/doc/manpage.d/ipsec_lwdnsq.8.html +++ /dev/null @@ -1,400 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC LWDNSQ - -

IPSEC LWDNSQ

-Section:  (8)
Updated:
Index -Return to Main Contents
- -  -

NAME

- -lwdnsq - lookup items in DNS to help pluto (and others) -  -

SYNOPSIS

- -

-

-ipsec lwdnsq lwdnsq [--prompt] [--serial]
-
- -

-

-ipsec lwdnsq lwdnsq [--help]
-
- -

-  -

DESCRIPTION

- -

-

- -The ipsec lwdnsq is a helper program that does DNS lookups for other programs. It implements an asynchronous interface on stdin/stdout, with an ASCII driven command language. -

-

- -If stdin is a tty or if the --prompt option is given, then it issues a prompt to the user. Otherwise, it is silent, except for results. -

-

- -The program will accept multiple queries concurrently, with each result being marked with the ID provided on the output. The IDs are strings. -

-

- -If the --serial option is given, then the program will not attempt to execute concurrent queries, but will serialize all input and output. -

-  -

QUERY LANGUAGE

- -

-

- -There are eleven command that the program understands. This is to lookup different types of records in both the forward and reverse maps. Every query includes a queryid, which is returned in the output, on every single line to identify the transaction. -

-  -

KEY queryid FQDN

- -

-

- -This request looks up the KEY resource record for the given FQDN.. -

-  -

KEY4 queryid A.B.C.D

- -

-

- -This request looks up the KEY resource record found in the reverse map for the IP version 4 address A.B.C.D, i.e. it looks up D.C.B.A.in-addr.arpa. -

-  -

KEY6 queryid A:B::C:D

- -

-

- -This request looks up the KEY resource record found in the reverse map for the IPv6 address A:B::C:D, i.e. it looks the 32-nibble long entry in ip6.arpa (and ip6.int). -

-  -

TXT4 queryid A.B.C.D

- -

-

- -This request looks up the TXT resource record found in the reverse map for the IP version 4 address A.B.C.D, i.e. it looks up D.C.B.A.in-addr.arpa. -

-  -

TXT6 queryid A:B::C:D

- -

-

- -This request looks up the TXT resource record found in the reverse map for the IPv6 address A:B::C:D, i.e. it looks the 32-nibble long entry in ip6.arpa (and ip6.int). -

-  -

KEY queryid FQDN

- -

-

- -This request looks up the IPSECKEY resource record for the given FQDN.. See note about IPSECKEY processing, below. -

-  -

IPSECKEY4 queryid A.B.C.D

- -

-

- -This request looks up the IPSECKEY resource record found in the reverse map for the IP version 4 address A.B.C.D, i.e. it looks up D.C.B.A.in-addr.arpa. See special note about IPSECKEY processing, below. -

-  -

IPSECKEY6 queryid A:B::C:D

- -

-

- -This request looks up the IPSECKEY resource record found in the reverse map for the IPv6 address A:B::C:D, i.e. it looks the 32-nibble long entry in ip6.arpa (and ip6.int). See special note about IPSECKEY processing, below. -

-  -

OE4 queryid A.B.C.D

- -

-

- -This request looks an appropriate record for Opportunistic Encryption for the given IP address. This attempts to look for the delegation record. This may be one of IPSECKEY, KEY, or TXT record. Unless configured otherwise, (see OE4 Directives, below), then a query type of ANY will be used to retrieve all relevant records, and all will be returned. -

-  -

OE6 queryid A:B::C:D

- -

-

- -This request looks an appropriate record for Opportunistic Encryption for the given IPv6 address. This attempts to look for the delegation record. This may be one of IPSECKEY, KEY, or TXT record. Unless configured otherwise, (see OE Directives, below), then a query type of ALL will be used to retrieve all relevant records, and all will be returned. i.e. it looks the 32-nibble long entry in ip6.arpa (and ip6.int). -

-  -

A queryid FQDN

- -

-

- -This request looks up the A (IPv4) resource record for the given FQDN.. -

-  -

AAAA queryid FQDN

- -

-

- -This request looks up the AAAA (IPv6) resource record for the given FQDN.. -

-  -

REPLIES TO QUERIES

- -

-

- -All replies from the queries are in the following format: -

-

-
-<ID> <TIME> <TTL> <TYPE> <TYPE-SPECIFIC> \n
-
-
- -
   -

-

-
ID
-this is the queryid value that was provided in the query. It is repeated on every line to permit the replies to be properly associated with the query. When the response is not ascribable to particular query (such as for a mis-formed query), then the query ID "0" will be used. -

-

TIME
-this is the current time in seconds since epoch. -

-

TTL
-for answers which have a time to live, this is the current value. The answer is valid for this number of seconds. If there is no useful value here, then the number 0 is used. -

-

TYPE
-This is the type of the record that is being returned. The types are described in the next section. The TYPE specific data that follows is specific to the type. -
  -

-

-

- -The replies are limited to 4096 bytes, a value defined as LWDNSQ_RESULT_LEN_MAX. This is defined in freeswan.h. -

-

- -All of the replies which include resource records use the standard presentation format (with no line feeds or carriage returns) in their answer. -

-  -

START

- -

-

- -This reply indicates that a query has been received and has been started. It serves as an anchor point for timing, as well as an acknowledgement. -

-  -

DONE

- -

-

- -This reply indicates that a query is entirely over, and no further information from this query will be sent. -

-  -

RETRY

- -

-

- -This reply indicates that a query is entirely over, but that no data was found. The records may exist, but appropriate servers could not be reached. -

-  -

FATAL

- -

-

- -This reply indicates that a query is entirely over, and that no data of the type requested could be found. There were no timeouts, and all servers were available and confirmed non-existances. There may be NXT records returned prior to this. -

-  -

CNAME

- -

-

- -This is an interim reply, and indicates that a CNAME was found (and followed) while performing the query. The value of the CNAME is present in the type specific section. -

-  -

CNAMEFROM

- -

-

- -This is an interim reply, and indicates that a CNAME was found. The original name that was queries for was not the canonical name, and this reply indicates the name that was actually followed. -

-  -

NAME

- -

-

- -This is an interim reply. The original name that was queries for was not the canonical name. This reply indicates the canonical name. -

-  -

DNSSEC

- -

-

- -This is an interim reply. It is followed either by "OKAY" or "not present. It indicates if DNSSEC was available on the reply. -

-  -

TXT and AD-TXT

- -

-

- -This is an interim reply. If there are TXT resource records in the reply, then each one is presented using this type. If preceeded by AD-, then this record was signed with DNSSEC. -

-  -

A and AD-A

- -

-

- -This is an interim reply. If there are A resource records in the reply, then each one is presented using this type. If preceeded by AD-, then this record was signed with DNSSEC. -

-  -

AAAA and AD-AAAA

- -

-

- -This is an interim reply. If there are AAAA resource records in the reply, then each one is presented using this type. If preceeded by AD-, then this record was signed with DNSSEC. -

-  -

PTR and AD-PTR

- -

-

- -This is an interim reply. If there are PTR resource records in the reply, then each one is presented using this type. If preceeded by AD-, then this record was signed with DNSSEC. -

-  -

KEY and AD-KEY

- -

-

- -This is an interim reply. If there are KEY resource records in the reply, then each one is presented using this type. If preceeded by AD-, then this record was signed with DNSSEC. -

-  -

IPSECKEY and AD-IPSECKEY

- -

-

- -This is an interim reply. If there are IPSEC resource records in the reply, then each one is presented using this type. If preceeded by AD-, then this record was signed with DNSSEC. -

-  -

SPECIAL IPSECKEY PROCESSING

- -

-

- -At the time of this writing, the IPSECKEY resource record is not entirely specified. In particular no resource record number has been assigned. This program assumes that it is resource record number 45. If the file /etc/ipsec.d/lwdnsq.conf exists, and contains a line like -

-

-
-ipseckey_rr=number
-
-
- -
 then this number will be used instead. The file is read only once at startup. -

-  -

OE DIRECTIVES

- -

-

- -If the file /etc/ipsec.d/lwdnsq.conf exists, and contains a line like -

-

-
-queryany=false
-
-
- -
 then instead of doing an ALL query when looking for OE delegation records, lwdnsq will do a series of queries. It will first look for IPSECKEY, and then TXT record. If it finds neither, it will then look for KEY records of all kinds, although they do not contain delegation information. -

-  -

SPECIAL IPSECKEY PROCESSING

- -

-

-
-/etc/ipsec.d/lwdnsq.conf
-
-
- -

-  -

AUTHOR

- -Michael Richardson <mcr@sandelman.ottawa.on.ca>. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
QUERY LANGUAGE
-
-
KEY queryid FQDN
-
KEY4 queryid A.B.C.D
-
KEY6 queryid A:B::C:D
-
TXT4 queryid A.B.C.D
-
TXT6 queryid A:B::C:D
-
KEY queryid FQDN
-
IPSECKEY4 queryid A.B.C.D
-
IPSECKEY6 queryid A:B::C:D
-
OE4 queryid A.B.C.D
-
OE6 queryid A:B::C:D
-
A queryid FQDN
-
AAAA queryid FQDN
-
-
REPLIES TO QUERIES
-
-
START
-
DONE
-
RETRY
-
FATAL
-
CNAME
-
CNAMEFROM
-
NAME
-
DNSSEC
-
TXT and AD-TXT
-
A and AD-A
-
AAAA and AD-AAAA
-
PTR and AD-PTR
-
KEY and AD-KEY
-
IPSECKEY and AD-IPSECKEY
-
-
SPECIAL IPSECKEY PROCESSING
-
OE DIRECTIVES
-
SPECIAL IPSECKEY PROCESSING
-
AUTHOR
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_mailkey.8.html b/doc/manpage.d/ipsec_mailkey.8.html deleted file mode 100644 index 83a532563..000000000 --- a/doc/manpage.d/ipsec_mailkey.8.html +++ /dev/null @@ -1,97 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_MAILKEY - -

IPSEC_MAILKEY

-Section: Maintenance Commands (8)
Updated: 21 Feb 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec mailkey - mail DNS records for Opportunistic Encryption -  -

SYNOPSIS

- -ipsec - -mailkey - ---me -my@address.tld -[ ---reverse - -1.2.3.4 -] [ ---forward - -hostname.domain.tld -] -  -

DESCRIPTION

- -mailkey - -is a meta-program. It generates a script which will attempt to mail the TXT -records required to enable Opportunistic Encryption (OE). -

- -An e-mail address for the domain's DNS administrator is derived from SOA records. -The mail body and destination address are freely editable in the script. -

- -If no administrator can be located, the output file will not be executable. -

- -

-
--me my@address.tld
-set the Reply-To: address of the mail to be sent. -
--forward hostname.domain.tld
-the domain name to be used for initator-only OE. -
--reverse 1.2.3.4
-the IP address to be used for full Opportunistic Encryption. -
-

- -Only one of --forward or --reverse may be specified. -  -

FILES

- -
-/etc/ipsec.secrets
-
- -  -

SEE ALSO

- -ipsec_showhostkey(8), host(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project <http://www.freeswan.org> by Sam Sgro. -  -

BUGS

- -May produce indeterminate results when processing non-routable IPs. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_manual.8.html b/doc/manpage.d/ipsec_manual.8.html deleted file mode 100644 index 77134f7d0..000000000 --- a/doc/manpage.d/ipsec_manual.8.html +++ /dev/null @@ -1,414 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_MANUAL - -

IPSEC_MANUAL

-Section: Maintenance Commands (8)
Updated: 17 July 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec manual - take manually-keyed IPsec connections up and down -  -

SYNOPSIS

- -ipsec - -manual - -[ ---show - -] [ ---showonly - -] [ ---other - -] -
- -   [ ---iam - -address@interface - -] [ ---config - -configfile -] -
- -   operation connection -

-ipsec - -manual - -[ -options - -] ---union - -operation part ... -  -

DESCRIPTION

- -Manual - -manipulates manually-keyed FreeS/WAN IPsec connections, -setting them up and shutting them down, -based on the information in the IPsec configuration file. -In the normal usage, -connection - -is the name of a connection specification in the configuration file; -operation - -is ---up, - ---down, - ---route, - -or ---unroute. - -Manual - -generates setup (--route - -or ---up) - -or -teardown (--down - -or ---unroute) - -commands for the connection and feeds them to a shell for execution. -

- -The ---up - -operation brings the specified connection up, including establishing a -suitable route for it if necessary. -

- -The ---route - -operation just establishes the route for a connection. -Unless and until an ---up - -operation is done, packets routed by that route will simply be discarded. -

- -The ---down - -operation tears the specified connection down, -except - -that it leaves the route in place. -Unless and until an ---unroute - -operation is done, packets routed by that route will simply be discarded. -This permits establishing another connection to the same destination -without any ``window'' in which packets can pass without encryption. -

- -The ---unroute - -operation (and only the ---unroute - -operation) deletes any route established for a connection. -

- -In the ---union - -usage, each -part - -is the name of a partial connection specification in the configuration file, -and the union of all the partial specifications is the -connection specification used. -The effect is as if the contents of the partial specifications were -concatenated together; -restrictions on duplicate parameters, etc., do apply to the result. -(The same effect can now be had, more gracefully, using the -also - -parameter in connection descriptions; -see -ipsec.conf(5) - -for details.) -

- -The ---show - -option turns on the --x - -option of the shell used to execute the commands, -so each command is shown as it is executed. -

- -The ---showonly - -option causes -manual - -to show the commands it would run, on standard output, -and not run them. -

- -The ---other - -option causes -manual - -to pretend it is the other end of the connection. -This is probably not useful except in combination with ---showonly. - -

- -The ---iam - -option causes -manual - -to believe it is running on the host with the specified IP -address, - -and that it should use the specified -interface - -(normally it determines all this automatically, -based on what IPsec interfaces are up and how they are configured). -

- -The ---config - -option specifies a non-standard location for the FreeS/WAN IPsec -configuration file (default -/etc/ipsec.conf). - -

- -See -ipsec.conf(5) - -for details of the configuration file. -Apart from the basic parameters which specify the endpoints and routing -of a connection (left -and -right, - -plus possibly -leftsubnet, - -leftnexthop, - -leftfirewall, - -their -right - -equivalents, -and perhaps -type), - -a non-passthrough -manual - -connection needs an -spi - -or -spibase - -parameter and some parameters specifying encryption, authentication, or -both, most simply -esp, - -espenckey, - -and -espauthkey. - -Moderately-secure keys can be obtained from -ipsec_ranbits(8). - -For production use of manually-keyed connections, -it is strongly recommended that the keys be kept in a separate file -(with permissions -rw-------) - -using the -include - -and -also - -facilities of the configuration file (see -ipsec.conf(5)). - -

- -If an -spi - -parameter is given, -manual - -uses that value as the SPI number for all the SAs -(which are in separate number spaces anyway). -If an -spibase - -parameter is given instead, -manual - -assigns SPI values by altering the bottom digit -of that value; -SAs going from left to right get even digits starting at 0, -SAs going from right to left get odd digits starting at 1. -Either way, it is suggested that manually-keyed connections use -three-digit SPIs with the first digit non-zero, -i.e. in the range -0x100 - -through -0xfff; - -FreeS/WAN reserves those for manual keying and will not -attempt to use them for automatic keying (unless requested to, -presumably by a non-FreeS/WAN other end). -  -

FILES

- - - -/etc/ipsec.conf           default IPsec configuration file
-
- -/var/run/ipsec.info      %defaultroute information
-  -

SEE ALSO

- -ipsec(8), ipsec.conf(5), ipsec_spi(8), ipsec_eroute(8), ipsec_spigrp(8), -route(8) -  -

HISTORY

- -Written for the FreeS/WAN project -<http://www.freeswan.org/> -by Henry Spencer. -  -

BUGS

- -It's not nearly as generous about the syntax of subnets, -addresses, etc. as the usual FreeS/WAN user interfaces. -Four-component dotted-decimal must be used for all addresses. -It -is - -smart enough to translate bit-count netmasks to dotted-decimal form. -

- -If the connection specification for a connection is changed between an ---up - -and the ensuing ---down, - -chaos may ensue. -

- -The ---up - -operation is not smart enough to notice whether the connection is already up. -

- -Manual - -is not smart enough to reject insecure combinations of algorithms, -e.g. encryption with no authentication at all. -

- -Any non-IPsec route to the other end which is replaced by the ---up - -or ---route - -operation will not be re-established by ---unroute. - -Whether this is a feature or a bug depends on your viewpoint. -

- -The optional parameters which -override the automatic -spibase-based - -SPI assignment are a messy area of the code and bugs are likely. -

- -``Road warrior'' handling, -and other special forms of setup which -require negotiation between the two security gateways, -inherently cannot be done with -manual. - -

- -Manual - -generally lags behind -auto - -in support of various features, -even when implementation would be possible. -For example, currently it does not do IPComp content compression. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_maskof.3.html b/doc/manpage.d/ipsec_maskof.3.html deleted file mode 100644 index ea0f83f82..000000000 --- a/doc/manpage.d/ipsec_maskof.3.html +++ /dev/null @@ -1,238 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITSUBNET - -

IPSEC_INITSUBNET

-Section: C Library Functions (3)
Updated: 12 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initsubnet - initialize an ip_subnet -
- -ipsec addrtosubnet - initialize a singleton ip_subnet -
- -ipsec subnettypeof - get address type of an ip_subnet -
- -ipsec masktocount - convert subnet mask to bit count -
- -ipsec networkof - get base address of an ip_subnet -
- -ipsec maskof - get subnet mask of an ip_subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initsubnet(const ip_address *addr, - -
-  -int maskbits, int clash, ip_subnet *dst); - -
- -const char *addrtosubnet(const ip_address *addr, - -
-  -ip_subnet *dst); - -

-int subnettypeof(const ip_subnet *src); - -
- -int masktocount(const ip_address *src); - -
- -void networkof(const ip_subnet *src, ip_address *dst); - -
- -void maskof(const ip_subnet *src, ip_address *dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_subnet - -to contain a description of an IP subnet -(base address plus mask). -These functions provide basic tools for creating and examining this type. -

- -Initsubnet - -initializes a variable -*dst - -of type -ip_subnet - -from a base address and -a count of mask bits. -The -clash - -parameter specifies what to do if the base address includes -1 - -bits outside the prefix specified by the mask -(that is, in the ``host number'' part of the address): -

-
-
'0'
-zero out host-number bits -
'x'
-non-zero host-number bits are an error -
-
- -

- -Initsubnet - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -Addrtosubnet - -initializes an -ip_subnet - -variable -*dst - -to a ``singleton subnet'' containing the single address -*addr. - -It returns -NULL - -for success and -a pointer to a string-literal error message for failure. -

- -Subnettypeof - -returns the address type of a subnet, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Masktocount - -converts a subnet mask, expressed as an address, to a bit count -suitable for use with -initsubnet. - -It returns --1 - -for error; see DIAGNOSTICS. -

- -Networkof - -fills in -*dst - -with the base address of subnet -src. - -

- -Maskof - -fills in -*dst - -with the subnet mask of subnet -src, - -expressed as an address. -  -

SEE ALSO

- -inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -initsubnet - -are: -unknown address family; -unknown -clash - -value; -impossible mask bit count; -non-zero host-number bits and -clash - -is -'x'. - -Fatal errors in -addrtosubnet - -are: -unknown address family. -Fatal errors in -masktocount - -are: -unknown address family; -mask bits not contiguous. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_masktobits.3.html b/doc/manpage.d/ipsec_masktobits.3.html deleted file mode 100644 index 6eccdd8d5..000000000 --- a/doc/manpage.d/ipsec_masktobits.3.html +++ /dev/null @@ -1,122 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_GOODMASK - -

IPSEC_GOODMASK

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec goodmask - is this Internet subnet mask a valid one? -
- -ipsec masktobits - convert Internet subnet mask to bit count -
- -ipsec bitstomask - convert bit count to Internet subnet mask -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int goodmask(struct in_addr mask); - -
- -int masktobits(struct in_addr mask); - -
- -struct in_addr bitstomask(int n); - -  -

DESCRIPTION

- -These functions are obsolete; -see -ipsec_masktocount(3) - -for a partial replacement. -

- -Goodmask - -reports whether the subnet -mask - -is a valid one, -i.e. consists of a (possibly empty) sequence of -1s - -followed by a (possibly empty) sequence of -0s. - -Masktobits - -takes a (valid) subnet mask and returns the number of -1 - -bits in it. -Bitstomask - -reverses this, -returning the subnet mask corresponding to bit count -n. - -

- -All masks are in network byte order. -  -

SEE ALSO

- -inet(3), ipsec_atosubnet(3) -  -

DIAGNOSTICS

- -Masktobits - -returns --1 - -for an invalid mask. -Bitstomask - -returns an all-zeros mask for a negative or out-of-range -n. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The error-reporting convention of -bitstomask - -is less than ideal; -zero is sometimes a legitimate mask. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_masktocount.3.html b/doc/manpage.d/ipsec_masktocount.3.html deleted file mode 100644 index ea0f83f82..000000000 --- a/doc/manpage.d/ipsec_masktocount.3.html +++ /dev/null @@ -1,238 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITSUBNET - -

IPSEC_INITSUBNET

-Section: C Library Functions (3)
Updated: 12 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initsubnet - initialize an ip_subnet -
- -ipsec addrtosubnet - initialize a singleton ip_subnet -
- -ipsec subnettypeof - get address type of an ip_subnet -
- -ipsec masktocount - convert subnet mask to bit count -
- -ipsec networkof - get base address of an ip_subnet -
- -ipsec maskof - get subnet mask of an ip_subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initsubnet(const ip_address *addr, - -
-  -int maskbits, int clash, ip_subnet *dst); - -
- -const char *addrtosubnet(const ip_address *addr, - -
-  -ip_subnet *dst); - -

-int subnettypeof(const ip_subnet *src); - -
- -int masktocount(const ip_address *src); - -
- -void networkof(const ip_subnet *src, ip_address *dst); - -
- -void maskof(const ip_subnet *src, ip_address *dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_subnet - -to contain a description of an IP subnet -(base address plus mask). -These functions provide basic tools for creating and examining this type. -

- -Initsubnet - -initializes a variable -*dst - -of type -ip_subnet - -from a base address and -a count of mask bits. -The -clash - -parameter specifies what to do if the base address includes -1 - -bits outside the prefix specified by the mask -(that is, in the ``host number'' part of the address): -

-
-
'0'
-zero out host-number bits -
'x'
-non-zero host-number bits are an error -
-
- -

- -Initsubnet - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -Addrtosubnet - -initializes an -ip_subnet - -variable -*dst - -to a ``singleton subnet'' containing the single address -*addr. - -It returns -NULL - -for success and -a pointer to a string-literal error message for failure. -

- -Subnettypeof - -returns the address type of a subnet, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Masktocount - -converts a subnet mask, expressed as an address, to a bit count -suitable for use with -initsubnet. - -It returns --1 - -for error; see DIAGNOSTICS. -

- -Networkof - -fills in -*dst - -with the base address of subnet -src. - -

- -Maskof - -fills in -*dst - -with the subnet mask of subnet -src, - -expressed as an address. -  -

SEE ALSO

- -inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -initsubnet - -are: -unknown address family; -unknown -clash - -value; -impossible mask bit count; -non-zero host-number bits and -clash - -is -'x'. - -Fatal errors in -addrtosubnet - -are: -unknown address family. -Fatal errors in -masktocount - -are: -unknown address family; -mask bits not contiguous. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_networkof.3.html b/doc/manpage.d/ipsec_networkof.3.html deleted file mode 100644 index ea0f83f82..000000000 --- a/doc/manpage.d/ipsec_networkof.3.html +++ /dev/null @@ -1,238 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITSUBNET - -

IPSEC_INITSUBNET

-Section: C Library Functions (3)
Updated: 12 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initsubnet - initialize an ip_subnet -
- -ipsec addrtosubnet - initialize a singleton ip_subnet -
- -ipsec subnettypeof - get address type of an ip_subnet -
- -ipsec masktocount - convert subnet mask to bit count -
- -ipsec networkof - get base address of an ip_subnet -
- -ipsec maskof - get subnet mask of an ip_subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initsubnet(const ip_address *addr, - -
-  -int maskbits, int clash, ip_subnet *dst); - -
- -const char *addrtosubnet(const ip_address *addr, - -
-  -ip_subnet *dst); - -

-int subnettypeof(const ip_subnet *src); - -
- -int masktocount(const ip_address *src); - -
- -void networkof(const ip_subnet *src, ip_address *dst); - -
- -void maskof(const ip_subnet *src, ip_address *dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_subnet - -to contain a description of an IP subnet -(base address plus mask). -These functions provide basic tools for creating and examining this type. -

- -Initsubnet - -initializes a variable -*dst - -of type -ip_subnet - -from a base address and -a count of mask bits. -The -clash - -parameter specifies what to do if the base address includes -1 - -bits outside the prefix specified by the mask -(that is, in the ``host number'' part of the address): -

-
-
'0'
-zero out host-number bits -
'x'
-non-zero host-number bits are an error -
-
- -

- -Initsubnet - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -Addrtosubnet - -initializes an -ip_subnet - -variable -*dst - -to a ``singleton subnet'' containing the single address -*addr. - -It returns -NULL - -for success and -a pointer to a string-literal error message for failure. -

- -Subnettypeof - -returns the address type of a subnet, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Masktocount - -converts a subnet mask, expressed as an address, to a bit count -suitable for use with -initsubnet. - -It returns --1 - -for error; see DIAGNOSTICS. -

- -Networkof - -fills in -*dst - -with the base address of subnet -src. - -

- -Maskof - -fills in -*dst - -with the subnet mask of subnet -src, - -expressed as an address. -  -

SEE ALSO

- -inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -initsubnet - -are: -unknown address family; -unknown -clash - -value; -impossible mask bit count; -non-zero host-number bits and -clash - -is -'x'. - -Fatal errors in -addrtosubnet - -are: -unknown address family. -Fatal errors in -masktocount - -are: -unknown address family; -mask bits not contiguous. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_newhostkey.8.html b/doc/manpage.d/ipsec_newhostkey.8.html deleted file mode 100644 index e6cf302bf..000000000 --- a/doc/manpage.d/ipsec_newhostkey.8.html +++ /dev/null @@ -1,196 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_NEWHOSTKEY - -

IPSEC_NEWHOSTKEY

-Section: Maintenance Commands (8)
Updated: 4 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec newhostkey - generate a new host authentication key -  -

SYNOPSIS

- -ipsec - -newhostkey - ---output - -filename -[ ---quiet - -] -\ - -
- - -[ ---bits - -n -] -[ ---hostname - -host -] -  -

DESCRIPTION

- -Newhostkey - -outputs (into -filename, - -which can be `-' for standard output) -an RSA private key suitable for this host, -in -/etc/ipsec.secrets - -format -(see -ipsec.secrets(5)). - -Normally, -newhostkey - -invokes -rsasigkey - -(see -ipsec_rsasigkey(8)) - -with the ---verbose - -option, so a narrative of what is being done appears on standard error. -

- -The ---output - -specifier, although it is syntactically an option and can appear at -any point among the options (it doesn't have to be first), -is not optional. -The specified -filename - -is created under umask -077 - -if nonexistent; -if it already exists and is non-empty, -a warning message about that is sent to standard error, -and the output is appended to the file. -

- -The ---quiet - -option suppresses both the -rsasigkey - -narrative and the existing-file warning message. -

- -The ---bits - -option specifies the number of bits in the key; -the current default is 2192 and we do not recommend use of anything -shorter unless unusual constraints demand it. -

- -The ---hostname - -option is passed through to -rsasigkey - -to tell it what host name to label the output with -(via its ---hostname - -option). -

- -The output format is that of -rsasigkey, - -with bracketing added to complete the -ipsec.secrets - -format. -In the usual case, where -ipsec.secrets - -contains only the host's own private key, -the output of -newhostkey - -is sufficient as a complete -ipsec.secrets - -file. -  -

SEE ALSO

- -ipsec.secrets(5), ipsec_rsasigkey(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -As with -rsasigkey, - -the run time is difficult to predict, -since depletion of the system's randomness pool can cause -arbitrarily long waits for random bits, -and the prime-number searches can also take unpredictable -(and potentially large) amounts of CPU time. -See -ipsec_rsasigkey(8) - -for some typical performance numbers. -

- -A higher-level tool which could handle the clerical details -of changing to a new key would be helpful. -

- -The requirement for ---output - -is a blemish, -but private keys are extremely sensitive information -and unusual precautions seem justified. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_optionsfrom.3.html b/doc/manpage.d/ipsec_optionsfrom.3.html deleted file mode 100644 index 05d045e4d..000000000 --- a/doc/manpage.d/ipsec_optionsfrom.3.html +++ /dev/null @@ -1,275 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_OPTIONSFROM - -

IPSEC_OPTIONSFROM

-Section: C Library Functions (3)
Updated: 16 Oct 1998
Index -Return to Main Contents
- - -  -

NAME

- -ipsec optionsfrom - read additional ``command-line'' options from file -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *optionsfrom(char *filename, int *argcp, - -
-  -char ***argvp, int optind, FILE *errsto); - -  -

DESCRIPTION

- -Optionsfrom - -is called from within a -getopt_long(3) - -scan, -as the result of the appearance of an option (preferably ---optionsfrom) - -to insert additional ``command-line'' arguments -into the scan immediately after -the option. -Typically this would be done to pick up options which are -security-sensitive and should not be visible to -ps(1) - -and similar commands, -and hence cannot be supplied as part -of the actual command line or the environment. -

- -Optionsfrom - -reads the additional arguments from the specified -filename, - -allocates a new argument vector to hold pointers to the existing -arguments plus the new ones, -and amends -argc - -and -argv - -(via the pointers -argcp - -and -argvp, - -which must point to the -argc - -and -argv - -being supplied to -getopt_long(3)) - -accordingly. -Optind - -must be the index, in the original argument vector, -of the next argument. -

- -If -errsto - -is NULL, -optionsfrom - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -If -errsto - -is non-NULL and an error occurs, -optionsfrom - -prints a suitable complaint onto the -errsto - -descriptor and invokes -exit - -with an exit status of 2; -this is a convenience for cases where more sophisticated -responses are not required. -

- -The text of existing arguments is not disturbed by -optionsfrom, - -so pointers to them and into them remain valid. -

- -The file of additional arguments is an ASCII text file. -Lines consisting solely of white space, -and lines beginning with -#, - -are comments and are ignored. -Otherwise, a line which does not begin with -- - -is taken to be a single argument; -if it both begins and ends with double-quote ("), -those quotes are stripped off (note, no other processing is done within -the line!). -A line beginning with -- - -is considered to contain multiple arguments separated by white space. -

- -Because -optionsfrom - -reads its entire file before the -getopt_long(3) - -scan is resumed, an -optionsfrom - -file can contain another ---optionsfrom - -option. -Obviously, infinite loops are possible here. -If -errsto - -is non-NULL, -optionsfrom - -considers it an error to be called more than 100 times. -If -errsto - -is NULL, -loop detection is up to the caller -(and the internal loop counter is zeroed out). -  -

EXAMPLE

- -A reasonable way to invoke -optionsfrom - -would be like so: -

- -

-#include <getopt.h>
-
-struct option opts[] = {
-        /* ... */
-        "optionsfrom",  1,      NULL,   '+',
-        /* ... */
-};
-
-int
-main(argc, argv)
-int argc;
-char *argv[];
-{
-        int opt;
-        extern char *optarg;
-        extern int optind;
-
-        while ((opt = getopt_long(argc, argv, "", opts, NULL)) != EOF)
-                switch (opt) {
-                /* ... */
-                case '+':       /* optionsfrom */
-                        optionsfrom(optarg, &argc, &argv, optind, stderr);
-                        /* does not return on error */
-                        break;
-                /* ... */
-                }
-        /* ... */
-
- -  -

SEE ALSO

- -getopt_long(3) -  -

DIAGNOSTICS

- -Errors in -optionsfrom - -are: -unable to open file; -attempt to allocate temporary storage for argument or -argument vector failed; -read error in file; -line too long. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The double-quote convention is rather simplistic. -

- -Line length is currently limited to 1023 bytes, -and there is no continuation convention. -

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -

- -There is a certain element of unwarranted chumminess with -the insides of -getopt_long(3) - -here. -No non-public interfaces are actually used, but -optionsfrom - -does rely on -getopt_long(3) - -being well-behaved in certain ways that are not actually -promised by the specs. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLE
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_pf_key.5.html b/doc/manpage.d/ipsec_pf_key.5.html deleted file mode 100644 index 420c12900..000000000 --- a/doc/manpage.d/ipsec_pf_key.5.html +++ /dev/null @@ -1,176 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PF_KEY - -

IPSEC_PF_KEY

-Section: File Formats (5)
Updated: 29 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_pf_key - lists PF_KEY sockets registered with KLIPS -  -

SYNOPSIS

- -cat - -/proc/net/pf_key - -  -

DESCRIPTION

- -/proc/net/pf_key - -is a read-only file which lists the presently open PF_KEY sockets on the -local system and their parameters. -

- -Each line lists one PF_KEY socket. -A table entry consists of: -

-
+
-sock pointer (sock) -
+
-PID of the socket owner (pid) -
+
-flag to indicate if the socket is dead (d) -
+
-socket wait queue (sleep) -
+
-socket pointer (socket) -
+
-next socket in chain (next) -
+
-previous socket in chain (prev) -
+
-last socket error (e) -
+
-pointer to destruct routine (destruct) -
+
-is this a reused socket (r) -
+
-has this socket been zapped (z) -
+
-socket family to which this socket belongs (fa) -
+
-local port number (n) -
+
-protocol version number (p) -
+
-Receive queue bytes committed (r) -
+
-Transmit queue bytes committed (w) -
+
-option memory allocations (o) -
+
-size of send buffer in bytes (sndbf) -
+
-timestamp in seconds (stamp) -
+
-socket flags (Flags) -
+
-socket type (Type) -
+
-connection state (St) -.SHEXAMPLES - -
-
-
c3b8c140 3553 0 c0599818 c05997fc 0 0 0 0 1 0 15 0 2 0 0 0 65535 0.103232 00000000 00000003 01 - -
-
-

- -shows that there is one pf_key socket set up that starts at -c3b8c140, - -whose owning process has PID -3553, - -the socket is not dead, its wait queue is at -c0599818, - -whose owning socket is at -c05997fc, - -with no other sockets in the chain, no errors, no destructor, it is a -reused socket which has not been zapped, from protocol family -15 - -(PF_KEY), local port number -0, - -protocol socket version -2, - -no memory allocated to transmit, receive or option queues, a send buffer -of almost -64kB, - -a timestamp of -0.103232, - -no flags set, type -3, - -in state -1. - -  -

FILES

- -/proc/net/pf_key -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_eroute(5), ipsec_spi(5), -ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_tncfg(8), ipsec_version(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_pf_key.8.html b/doc/manpage.d/ipsec_pf_key.8.html deleted file mode 100644 index e40cfb15b..000000000 --- a/doc/manpage.d/ipsec_pf_key.8.html +++ /dev/null @@ -1,122 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PF_KEY - -

IPSEC_PF_KEY

-Section: User Commands (1)
Updated: 17 Oct 2001
Index -Return to Main Contents
- - - - -  -

NAME

- -pf_key - shows pfkey messages emitted by the kernel -  -

SYNOPSIS

- -pf_key - ---ah - ---esp - ---ipip - ---ipcomp - ---daemon - -file - -hmac-md5-96|hmac-sha1-96 - -  -

DESCRIPTION

- -pf_key - -is a program to open a PF_KEY socket and print all messages that are received -from it. With no options, it will register itself to receive key requests for -AH, ESP, IPIP and IPCOMP security associations. If given more specific -options, then it will listen only to those protocols which are listed. -

- -If the messages are recognized, the messages will be decoded. -

- -If the option ---daemon - -is provided, then after doing the registrations, the program will fork -into the background. The provided file will be opened and the process ID of -the background process will be written to it. This option is present to -present race conditions in regression testing. -  -

EXAMPLES

- -
-
-
-
-  -

FILES

- -/proc/net/pf_key -  -

SEE ALSO

- -pf_key(5), ipsec(8), ipsec_manual(8), ipsec_eroute(5), ipsec_spi(5), -ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_tncfg(8), ipsec_version(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Michael Richardson <mcr@freeswan.org> - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_pluto.8.html b/doc/manpage.d/ipsec_pluto.8.html deleted file mode 100644 index 2e2ce4c2f..000000000 --- a/doc/manpage.d/ipsec_pluto.8.html +++ /dev/null @@ -1,1824 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PLUTO - -

IPSEC_PLUTO

-Section: Maintenance Commands (8)
Updated: 28 March 1999
Index -Return to Main Contents
- -  -

NAME

- -ipsec pluto - IPsec IKE keying daemon -
- -ipsec whack - control interface for IPSEC keying daemon -  -

SYNOPSIS

- - - -
-
- -
ipsec pluto -[--help] -[--version] -[--optionsfrom filename] -[--nofork] -[--stderrlog] -[--noklips] -[--uniqueids] -[--interface interfacename] -[--ikeport portnumber] -[--ctlbase path] -[--secretsfile secrets-file] -[--adns pathname] -[--lwdnsq pathname] -[--perpeerlog] -[--perpeerlogbase dirname] -[--debug-none] -[--debug-all] -[--debug-raw] -[--debug-crypt] -[--debug-parsing] -[--debug-emitting] -[--debug-control] -[--debug-lifecycle] -[--debug-klips] -[--debug-dns] -[--debug-oppo] -[--debug-private] -
- -
ipsec whack -[--help] -[--version] -
- -
ipsec whack ---name connection-name -
- -[--id id] [--host ip-address] -[--ikeport port-number] -[--nexthop ip-address] -[--client subnet] -[--dnskeyondemand] -[--updown updown] -
- ---to -
- -[--id id] -[--host ip-address] -[--ikeport port-number] -[--nexthop ip-address] -[--client subnet] -[--dnskeyondemand] -[--updown updown] -
- -[--psk] -[--rsasig] -[--encrypt] -[--authenticate] -[--compress] -[--tunnel] -[--pfs] -[--disablearrivalcheck] -[--ipv4] -[--ipv6] -[--tunnelipv4] -[--tunnelipv6] -[--ikelifetime seconds] -[--ipseclifetime seconds] -[--rekeymargin seconds] -[--rekeyfuzz percentage] -[--keyingtries count] -[--dontrekey] -[--delete] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---keyid id -[--addkey] -[--pubkeyrsa key] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---myid id -
- -
ipsec whack ---listen|--unlisten -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---route|--unroute ---name connection-name -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---initiate|--terminate ---name connection-name -[--asynchronous] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack -[--tunnelipv4] -[--tunnelipv6] ---oppohere ip-address ---oppothere ip-address -
- -
ipsec whack ---delete ---name connection-name -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---deletestate state-number -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack -[--name connection-name] -[--debug-none] -[--debug-all] -[--debug-raw] -[--debug-crypt] -[--debug-parsing] -[--debug-emitting] -[--debug-control] -[--debug-lifecycle] -[--debug-klips] -[--debug-dns] -[--debug-oppo] -[--debug-private] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---status -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---shutdown -[--ctlbase path] -[--optionsfrom filename] -[--label string] - - - -
-  -

DESCRIPTION

- -pluto - -is an IKE (``IPsec Key Exchange'') daemon. -whack - -is an auxiliary program to allow requests to be made to a running -pluto. - -

- -pluto - -is used to automatically build shared ``security associations'' on a -system that has IPsec, the secure IP protocol. -In other words, -pluto - -can eliminate much of the work of manual keying. -The actual -secure transmission of packets is the responsibility of other parts of -the system (see -KLIPS, - -the companion implementation of IPsec). -ipsec_auto(8) provides a more convenient interface to -pluto and whack. -  -

IKE's Job

- -

- -A Security Association (SA) is an agreement between two network nodes on -how to process certain traffic between them. This processing involves -encapsulation, authentication, encryption, or compression. -

- -IKE can be deployed on a network node to negotiate Security -Associations for that node. These IKE implementations can only -negotiate with other IKE implementations, so IKE must be on each node -that is to be an endpoint of an IKE-negotiated Security Association. -No other nodes need to be running IKE. -

- -An IKE instance (i.e. an IKE implementation on a particular network -node) communicates with another IKE instance using UDP IP packets, so -there must be a route between the nodes in each direction. -

- -The negotiation of Security Associations requires a number of choices -that involve tradeoffs between security, convenience, trust, and -efficiency. These are policy issues and are normally specified to the -IKE instance by the system administrator. -

- -IKE deals with two kinds of Security Associations. The first part of -a negotiation between IKE instances is to build an ISAKMP SA. An -ISAKMP SA is used to protect communication between the two IKEs. -IPsec SAs can then be built by the IKEs - these are used to carry -protected IP traffic between the systems. -

- -The negotiation of the ISAKMP SA is known as Phase 1. In theory, -Phase 1 can be accomplished by a couple of different exchange types, -but we only implement one called Main Mode (we don't implement -Aggressive Mode). -

- -Any negotiation under the protection of an ISAKMP SA, including the -negotiation of IPsec SAs, is part of Phase 2. The exchange type -that we use to negotiate an IPsec SA is called Quick Mode. -

- -IKE instances must be able to authenticate each other as part of their -negotiation of an ISAKMP SA. This can be done by several mechanisms -described in the draft standards. -

- -IKE negotiation can be initiated by any instance with any other. If -both can find an agreeable set of characteristics for a Security -Association, and both recognize each others authenticity, they can set -up a Security Association. The standards do not specify what causes -an IKE instance to initiate a negotiation. -

- -In summary, an IKE instance is prepared to automate the management of -Security Associations in an IPsec environment, but a number of issues -are considered policy and are left in the system administrator's hands. -  -

Pluto

- -

- -pluto is an implementation of IKE. It runs as a daemon on a network -node. Currently, this network node must be a LINUX system running the -KLIPS implementation of IPsec. -

- -pluto only implements a subset of IKE. This is enough for it to -interoperate with other instances of pluto, and many other IKE -implementations. We are working on implementing more of IKE. -

- -The policy for acceptable characteristics for Security Associations is -mostly hardwired into the code of pluto (spdb.c). Eventually -this will be moved into a security policy database with reasonable -expressive power and more convenience. -

- -pluto uses shared secrets or RSA signatures to authenticate -peers with whom it is negotiating. -

- -pluto initiates negotiation of a Security Association when it is -manually prodded: the program whack is run to trigger this. -It will also initiate a negotiation when KLIPS traps an outbound packet -for Opportunistic Encryption. -

- -pluto implements ISAKMP SAs itself. After it has negotiated the -characteristics of an IPsec SA, it directs KLIPS to implement it. -It also invokes a script to adjust any firewall and issue route(8) -commands to direct IP packets through KLIPS. -

- -When pluto shuts down, it closes all Security Associations. -  -

Before Running Pluto

- -

- -pluto runs as a daemon with userid root. Before running it, a few -things must be set up. -

- -pluto requires KLIPS, the FreeS/WAN implementation of IPsec. -All of the components of KLIPS and pluto should be installed. -

- -pluto supports multiple public networks (that is, networks -that are considered insecure and thus need to have their traffic -encrypted or authenticated). It discovers the -public interfaces to use by looking at all interfaces that are -configured (the --interface option can be used to limit -the interfaces considered). -It does this only when whack tells it to --listen, -so the interfaces must be configured by then. Each interface with a name of the form -ipsec[0-9] is taken as a KLIPS virtual public interface. -Another network interface with the same IP address (there should be only -one) is taken as the corresponding real public -interface. ifconfig(8) with the -a flag will show -the name and status of each network interface. -

- -pluto requires a database of preshared secrets and RSA private keys. -This is described in the -ipsec.secrets(5). - -pluto is told of RSA public keys via whack commands. -If the connection is Opportunistic, and no RSA public key is known, -pluto will attempt to fetch RSA keys using the Domain Name System. -  -

Setting up KLIPS for pluto

- -

- -The most basic network topology that pluto supports has two security -gateways negotiating on behalf of client subnets. The diagram of RGB's -testbed is a good example (see klips/doc/rgb_setup.txt). -

- -The file INSTALL in the base directory of this distribution -explains how to start setting up the whole system, including KLIPS. -

- -Make sure that the security gateways have routes to each other. This -is usually covered by the default route, but may require issuing -route(8) - -commands. The route must go through a particular IP -interface (we will assume it is eth0, but it need not be). The -interface that connects the security gateway to its client must be a -different one. -

- -It is necessary to issue a -ipsec_tncfg(8) - -command on each gateway. The required command is: -

-   ipsec tncfg --attach --virtual ipsec0 --physical eth0 -

-A command to set up the ipsec0 virtual interface will also need to be -run. It will have the same parameters as the command used to set up -the physical interface to which it has just been connected using -ipsec_tncfg(8). - -  -

ipsec.secrets file

- -

- -A pluto daemon and another IKE daemon (for example, another instance -of pluto) must convince each other that they are who they are supposed -to be before any negotiation can succeed. This authentication is -accomplished by using either secrets that have been shared beforehand -(manually) or by using RSA signatures. There are other techniques, -but they have not been implemented in pluto. -

- -The file /etc/ipsec.secrets is used to keep preshared secret keys -and RSA private keys for -authentication with other IKE daemons. For debugging, there is an -argument to the pluto command to use a different file. -This file is described in -ipsec.secrets(5). - -  -

Running Pluto

- -

- -To fire up the daemon, just type pluto (be sure to be running as -the superuser). -The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. -pluto must be run by the superuser to be able to use the UDP 500 port. -

- -pluto attempts to create a lockfile with the name -/var/run/pluto.pid. If the lockfile cannot be created, -pluto exits - this prevents multiple plutos from -competing Any ``leftover'' lockfile must be removed before -pluto will run. pluto writes its pid into this file so -that scripts can find it. This lock will not function properly if it -is on an NFS volume (but sharing locks on multiple machines doesn't -make sense anyway). -

- -pluto then forks and the parent exits. This is the conventional -``daemon fork''. It can make debugging awkward, so there is an option -to suppress this fork. -

- -All logging, including diagnostics, is sent to -syslog(3) - -with facility=authpriv; -it decides where to put these messages (possibly in /var/log/secure). -Since this too can make debugging awkward, there is an option to -steer logging to stderr. -

- -If the --perpeerlog option is given, then pluto will open -a log file per connection. By default, this is in /var/log/pluto/peer, -in a subdirectory formed by turning all dot (.) [IPv4} or colon (:) -[IPv6] into slashes (/). -

- -The base directory can be changed with the --perpeerlogbase. -

- -Once pluto is started, it waits for requests from whack. -  -

Pluto's Internal State

- -

- -To understand how to use pluto, it is helpful to understand a little -about its internal state. Furthermore, the terminology is needed to decipher -some of the diagnostic messages. -

- -The (potential) connection database describes attributes of a -connection. These include the IP addresses of the hosts and client -subnets and the security characteristics desired. pluto -requires this information (simply called a connection) before it can -respond to a request to build an SA. Each connection is given a name -when it is created, and all references are made using this name. -

- -During the IKE exchange to build an SA, the information about the -negotiation is represented in a state object. Each state object -reflects how far the negotiation has reached. Once the negotiation is -complete and the SA established, the state object remains to represent -the SA. When the SA is terminated, the state object is discarded. -Each State object is given a serial number and this is used to refer -to the state objects in logged messages. -

- -Each state object corresponds to a connection and can be thought of -as an instantiation of that connection. -At any particular time, there may be any number of state objects -corresponding to a particular connection. -Often there is one representing an ISAKMP SA and another representing -an IPsec SA. -

- -KLIPS hooks into the routing code in a LINUX kernel. -Traffic to be processed by an IPsec SA must be directed through -KLIPS by routing commands. Furthermore, the processing to be -done is specified by ipsec eroute(8) commands. -pluto takes the responsibility of managing both of these special -kinds of routes. -

- -Each connection may be routed, and must be while it has an IPsec SA. -The connection specifies the characteristics of the route: the -interface on this machine, the ``gateway'' (the nexthop), -and the peer's client subnet. Two -connections may not be simultaneously routed if they are for the same -peer's client subnet but use different interfaces or gateways -(pluto's logic does not reflect any advanced routing capabilities). -

- -Each eroute is associated with the state object for an IPsec SA -because it has the particular characteristics of the SA. -Two eroutes conflict if they specify the identical local -and remote clients (unlike for routes, the local clients are -taken into account). -

- -When pluto needs to install a route for a connection, -it must make sure that no conflicting route is in use. If another -connection has a conflicting route, that route will be taken down, as long -as there is no IPsec SA instantiating that connection. -If there is such an IPsec SA, the attempt to install a route will fail. -

- -There is an exception. If pluto, as Responder, needs to install -a route to a fixed client subnet for a connection, and there is -already a conflicting route, then the SAs using the route are deleted -to make room for the new SAs. The rationale is that the new -connection is probably more current. The need for this usually is a -product of Road Warrior connections (these are explained later; they -cannot be used to initiate). -

- -When pluto needs to install an eroute for an IPsec SA (for a -state object), first the state object's connection must be routed (if -this cannot be done, the eroute and SA will not be installed). -If a conflicting eroute is already in place for another connection, -the eroute and SA will not be installed (but note that the routing -exception mentioned above may have already deleted potentially conflicting SAs). -If another IPsec -SA for the same connection already has an eroute, all its outgoing traffic -is taken over by the new eroute. The incoming traffic will still be -processed. This characteristic is exploited during rekeying. -

- -All of these routing characteristics are expected change when -KLIPS is modified to use the firewall hooks in the LINUX 2.4.x -kernel. -  -

Using Whack

- -

- -whack is used to command a running pluto. -whack uses a UNIX domain socket to speak to pluto -(by default, /var/pluto.ctl). -

- -whack has an intricate argument syntax. -This syntax allows many different functions to be specified. -The help form shows the usage or version information. -The connection form gives pluto a description of a potential connection. -The public key form informs pluto of the RSA public key for a potential peer. -The delete form deletes a connection description and all SAs corresponding -to it. -The listen form tells pluto to start or stop listening on the public interfaces -for IKE requests from peers. -The route form tells pluto to set up routing for a connection; -the unroute form undoes this. -The initiate form tells pluto to negotiate an SA corresponding to a connection. -The terminate form tells pluto to remove all SAs corresponding to a connection, -including those being negotiated. -The status form displays the pluto's internal state. -The debug form tells pluto to change the selection of debugging output -``on the fly''. The shutdown form tells -pluto to shut down, deleting all SAs. -

- -Most options are specific to one of the forms, and will be described -with that form. There are three options that apply to all forms. -

-
--ctlbase path
-path.ctl is used as the UNIX domain socket for talking -to pluto. -This option facilitates debugging. -
--optionsfrom filename
-adds the contents of the file to the argument list. -
--label string
-adds the string to all error messages generated by whack. -
-

- -The help form of whack is self-explanatory. -

-
--help
-display the usage message. -
--version
-display the version of whack. -
-

- -The connection form describes a potential connection to pluto. -pluto needs to know what connections can and should be negotiated. -When pluto is the initiator, it needs to know what to propose. -When pluto is the responder, it needs to know enough to decide whether -is is willing to set up the proposed connection. -

- -The description of a potential connection can specify a large number -of details. Each connection has a unique name. This name will appear -in a updown shell command, so it should not contain punctuation -that would make the command ill-formed. -

-
--name connection-name
-
-

- -The topology of -a connection is symmetric, so to save space here is half a picture: -

-   client_subnet<-->host:ikeport<-->nexthop<--- -

-A similar trick is used in the flags. The same flag names are used for -both ends. Those before the --to flag describe the left side -and those afterwards describe the right side. When pluto attempts -to use the connection, it decides whether it is the left side or the right -side of the connection, based on the IP numbers of its interfaces. -

-
--id id
-the identity of the end. Currently, this can be an IP address (specified -as dotted quad or as a Fully Qualified Domain Name, which will be resolved -immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@'' -to signify that it should not be resolved), or as user@FQDN, or as the -magic value %myid. -Pluto only authenticates the identity, and does not use it for -addressing, so, for example, an IP address need not be the one to which -packets are to be sent. If the option is absent, the -identity defaults to the IP address specified by --host. -%myid allows the identity to be separately specified (by the pluto or whack option --myid -or by the ipsec.conf(5) config setup parameter myid). -Otherwise, pluto tries to guess what %myid should stand for: -the IP address of %defaultroute, if it is supported by a suitable TXT record in the reverse domain for that IP address, -or the system's hostname, if it is supported by a suitable TXT record in its forward domain. - -
--host ip-address
-
--host %any
-
--host %opportunistic
-the IP address of the end (generally the public interface). -If pluto is to act as a responder -for IKE negotiations initiated from unknown IP addresses (the -``Road Warrior'' case), the -IP address should be specified as %any (currently, -the obsolete notation 0.0.0.0 is also accepted for this). -If pluto is to opportunistically initiate the connection, -use %opportunistic -
--ikeport port-number
-the UDP port that IKE listens to on that host. The default is 500. -(pluto on this machine uses the port specified by its own command -line argument, so this only affects where pluto sends messages.) -
--nexthop ip-address
-where to route packets for the peer's client (presumably for the peer too, -but it will not be used for this). -When pluto installs an IPsec SA, it issues a route command. -It uses the nexthop as the gateway. -The default is the peer's IP address (this can be explicitly written as -%direct; the obsolete notation 0.0.0.0 is accepted). -This option is necessary if pluto's host's interface used for sending -packets to the peer is neither point-to-point nor directly connected to the -peer. -
--client subnet
-the subnet for which the IPsec traffic will be destined. If not specified, -the host will be the client. -The subnet can be specified in any of the forms supported by ipsec_atosubnet(3). -The general form is address/mask. The address can be either -a domain name or four decimal numbers (specifying octets) separated by dots. -The most convenient form of the mask is a decimal integer, specifying -the number of leading one bits in the mask. So, for example, 10.0.0.0/8 -would specify the class A network ``Net 10''. -
--dnskeyondemand]
-specifies that when an RSA public key is needed to authenticate this -host, and it isn't already known, fetch it from DNS. -
--updown updown
-specifies an external shell command to be run whenever pluto -brings up or down a connection. -The script is used to build a shell command, so it may contain positional -parameters, but ought not to have punctuation that would cause the -resulting command to be ill-formed. -The default is ipsec _updown. -
--to
-separates the specification of the left and right ends of the connection. -
-

- -The potential connection description also specifies characteristics of -rekeying and security. -

-
--psk
-Propose and allow preshared secret authentication for IKE peers. This authentication -requires that each side use the same secret. May be combined with --rsasig; -at least one must be specified. -
--rsasig
-Propose and allow RSA signatures for authentication of IKE peers. This authentication -requires that each side have have a private key of its own and know the -public key of its peer. May be combined with --psk; -at least one must be specified. -
--encrypt
-All proposed or accepted IPsec SAs will include non-null ESP. -The actual choices of transforms are wired into pluto. -
--authenticate
-All proposed IPsec SAs will include AH. -All accepted IPsec SAs will include AH or ESP with authentication. -The actual choices of transforms are wired into pluto. -Note that this has nothing to do with IKE authentication. -
--compress
-All proposed IPsec SAs will include IPCOMP (compression). -This will be ignored if KLIPS is not configured with IPCOMP support. -
--tunnel
-the IPsec SA should use tunneling. Implicit if the SA is for clients. -Must only be used with --authenticate or --encrypt. -
--ipv4
-The host addresses will be interpreted as IPv4 addresses. This is the -default. Note that for a connection, all host addresses must be of -the same Address Family (IPv4 and IPv6 use different Address Families). -
--ipv6
-The host addresses (including nexthop) will be interpreted as IPv6 addresses. -Note that for a connection, all host addresses must be of -the same Address Family (IPv4 and IPv6 use different Address Families). -
--tunnelipv4
-The client addresses will be interpreted as IPv4 addresses. The default is -to match what the host will be. This does not imply --tunnel so the -flag can be safely used when no tunnel is actually specified. -Note that for a connection, all tunnel addresses must be of the same -Address Family. -
--tunnelipv6
-The client addresses will be interpreted as IPv6 addresses. The default is -to match what the host will be. This does not imply --tunnel so the -flag can be safely used when no tunnel is actually specified. -Note that for a connection, all tunnel addresses must be of the same -Address Family. -
--pfs
-There should be Perfect Forward Secrecy - new keying material will -be generated for each IPsec SA rather than being derived from the ISAKMP -SA keying material. -Since the group to be used cannot be negotiated (a dubious feature of the -standard), pluto will propose the same group that was used during Phase 1. -We don't implement a stronger form of PFS which would require that the -ISAKMP SA be deleted after the IPSEC SA is negotiated. -
--disablearrivalcheck
-If the connection is a tunnel, allow packets arriving through the tunnel -to have any source and destination addresses. -
-

- -If none of the --encrypt, --authenticate, --compress, -or --pfs flags is given, the initiating the connection will -only build an ISAKMP SA. For such a connection, client subnets have -no meaning and must not be specified. -

- -More work is needed to allow for flexible policies. Currently -policy is hardwired in the source file spdb.c. The ISAKMP SAs may use -Oakley groups MODP1024 and MODP1536; 3DES encryption; SHA1-96 -and MD5-96 authentication. The IPsec SAs may use 3DES and -MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. -IPCOMP Compression is always Deflate. -

-
--ikelifetime seconds
-how long pluto will propose that an ISAKMP SA be allowed to live. -The default is 3600 (one hour) and the maximum is 28800 (8 hours). -This option will not affect what is accepted. -pluto will reject proposals that exceed the maximum. -
--ipseclifetime seconds
-how long pluto will propose that an IPsec SA be allowed to live. -The default is 28800 (eight hours) and the maximum is 86400 (one day). -This option will not affect what is accepted. -pluto will reject proposals that exceed the maximum. -
--rekeymargin seconds
-how long before an SA's expiration should pluto try to negotiate -a replacement SA. This will only happen if pluto was the initiator. -The default is 540 (nine minutes). -
--rekeyfuzz percentage
-maximum size of random component to add to rekeymargin, expressed as -a percentage of rekeymargin. pluto will select a delay uniformly -distributed within this range. By default, the percentage will be 100. -If greater determinism is desired, specify 0. It may be appropriate -for the percentage to be much larger than 100. -
--keyingtries count
-how many times pluto should try to negotiate an SA, -either for the first time or for rekeying. -A value of 0 is interpreted as a very large number: never give up. -The default is three. -
--dontrekey
-A misnomer. -Only rekey a connection if we were the Initiator and there was recent -traffic on the existing connection. -This applies to Phase 1 and Phase 2. -This is currently the only automatic way for a connection to terminate. -It may be useful with Road Warrior or Opportunistic connections. -
- -Since SA lifetime negotiation is take-it-or-leave it, a Responder -normally uses the shorter of the negotiated or the configured lifetime. -This only works because if the lifetime is shorter than negotiated, -the Responder will rekey in time so that everything works. -This interacts badly with --dontrekey. In this case, -the Responder will end up rekeying to rectify a shortfall in an IPsec SA -lifetime; for an ISAKMP SA, the Responder will accept the negotiated -lifetime. -
--delete
-when used in the connection form, it causes any previous connection -with this name to be deleted before this one is added. Unlike a -normal delete, no diagnostic is produced if there was no previous -connection to delete. Any routing in place for the connection is undone. -
-

- -The delete form deletes a named connection description and any -SAs established or negotiations initiated using this connection. -Any routing in place for the connection is undone. -

-
--delete
-
--name connection-name
-
-

- -The deletestate form deletes the state object with the specified serial number. -This is useful for selectively deleting instances of connections. -

-
--deletestate state-number
-
-

- -The route form of the whack command tells pluto to set up -routing for a connection. -Although like a traditional route, it uses an ipsec device as a -virtual interface. -Once routing is set up, no packets will be -sent ``in the clear'' to the peer's client specified in the connection. -A TRAP shunt eroute will be installed; if outbound traffic is caught, -Pluto will initiate the connection. -An explicit whack route is not always needed: if it hasn't been -done when an IPsec SA is being installed, one will be automatically attempted. -

- -When a routing is attempted for a connection, there must not already -be a routing for a different connection with the same subnet but different -interface or destination, or if -there is, it must not be being used by an IPsec SA. Otherwise the -attempt will fail. -

-
--route
-
--name connection-name
-
-

- -The unroute form of the whack command tells pluto to undo -a routing. pluto will refuse if an IPsec SA is using the connection. -If another connection is sharing the same routing, it will be left in place. -Without a routing, packets will be sent without encryption or authentication. -

-
--unroute
-
--name connection-name
-
-

- -The initiate form tells pluto to initiate a negotiation with another -pluto (or other IKE daemon) according to the named connection. -Initiation requires a route that --route would provide; -if none is in place at the time an IPsec SA is being installed, -pluto attempts to set one up. -

-
--initiate
-
--name connection-name
-
--asynchronous
-
-

- -The initiate form of the whack command will relay back from -pluto status information via the UNIX domain socket (unless ---asynchronous is specified). The status information is meant to -look a bit like that from FTP. Currently whack simply -copies this to stderr. When the request is finished (eg. the SAs are -established or pluto gives up), pluto closes the channel, -causing whack to terminate. -

- -The opportunistic initiate form is mainly used for debugging. -

-
--tunnelipv4
-
--tunnelipv6
-
--oppohere ip-address
-
--oppothere ip-address
-
-

- -This will cause pluto to attempt to opportunistically initiate a -connection from here to the there, even if a previous attempt -had been made. -The whack log will show the progress of this attempt. -

- -The terminate form tells pluto to delete any SAs that use the specified -connection and to stop any negotiations in process. -It does not prevent new negotiations from starting (the delete form -has this effect). -

-
--terminate
-
--name connection-name
-
-

- -The public key for informs pluto of the RSA public key for a potential peer. -Private keys must be kept secret, so they are kept in -ipsec.secrets(5). - -

-
--keyid id
-specififies the identity of the peer for which a public key should be used. -Its form is identical to the identity in the connection. -If no public key is specified, pluto attempts to find KEY records -from DNS for the id (if a FQDN) or through reverse lookup (if an IP address). -Note that there several interesting ways in which this is not secure. -
--addkey
-specifies that the new key is added to the collection; otherwise the -new key replaces any old ones. -
--pubkeyrsa key
-specifies the value of the RSA public key. It is a sequence of bytes -as described in RFC 2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''. -It is denoted in a way suitable for ipsec_ttodata(3). -For example, a base 64 numeral starts with 0s. -
-

- -The listen form tells pluto to start listening for IKE requests -on its public interfaces. To avoid race conditions, it is normal to -load the appropriate connections into pluto before allowing it -to listen. If pluto isn't listening, it is pointless to -initiate negotiations, so it will refuse requests to do so. Whenever -the listen form is used, pluto looks for public interfaces and -will notice when new ones have been added and when old ones have been -removed. This is also the trigger for pluto to read the -ipsec.secrets file. So listen may useful more than once. -

-
--listen
-start listening for IKE traffic on public interfaces. -
--unlisten
-stop listening for IKE traffic on public interfaces. -
-

- -The status form will display information about the internal state of -pluto: information about each potential connection, about -each state object, and about each shunt that pluto is managing -without an associated connection. -

-
--status
-
-

- -The shutdown form is the proper way to shut down pluto. -It will tear down the SAs on this machine that pluto has negotiated. -It does not inform its peers, so the SAs on their machines remain. -

-
--shutdown
-
-  -

Examples

- -

- -It would be normal to start pluto in one of the system initialization -scripts. It needs to be run by the superuser. Generally, no arguments are needed. -To run in manually, the superuser can simply type -

-   ipsec pluto -

-The command will immediately return, but a pluto process will be left -running, waiting for requests from whack or a peer. -

- -Using whack, several potential connections would be described: -

-
- -   ipsec whack --name silly ---host 127.0.0.1 --to --host 127.0.0.2 ---ikelifetime 900 --ipseclifetime 800 --keyingtries 3 - -
-

- -

Since this silly connection description specifies neither encryption, -authentication, nor tunneling, it could only be used to establish -an ISAKMP SA. -
-
- -   ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 ---to --host 10.0.0.2 --client 10.0.2.0/24 ---encrypt - -
-

- -

This is something that must be done on both sides. If the other -side is pluto, the same whack command could be used on it -(the command syntax is designed to not distinguish which end is ours). -

- -Now that the connections are specified, pluto is ready to handle -requests and replies via the public interfaces. We must tell it to discover -those interfaces and start accepting messages from peers: -

-   ipsec whack --listen -

- -If we don't immediately wish to bring up a secure connection between -the two clients, we might wish to prevent insecure traffic. -The routing form asks pluto to cause the packets sent from -our client to the peer's client to be routed through the ipsec0 -device; if there is no SA, they will be discarded: -

-   ipsec whack --route secret -

- -Finally, we are ready to get pluto to initiate negotiation -for an IPsec SA (and implicitly, an ISAKMP SA): -

-   ipsec whack --initiate --name secret -

-A small log of interesting events will appear on standard output -(other logging is sent to syslog). -

- -whack can also be used to terminate pluto cleanly, tearing down -all SAs that it has negotiated. -

-   ipsec whack --shutdown -

-Notification of any IPSEC SA deletion, but not ISAKMP SA deletion -is sent to the peer. Unfortunately, such Notification is not reliable. -Furthermore, pluto itself ignores Notifications. -  -

The updown command

- -

- -Whenever pluto brings a connection up or down, it invokes -the updown command. This command is specified using the --updown -option. This allows for customized control over routing and firewall manipulation. -

- -The updown is invoked for five different operations. Each of -these operations can be for our client subnet or for our host itself. -

-
prepare-host or prepare-client
-is run before bringing up a new connection if no other connection -with the same clients is up. Generally, this is useful for deleting a -route that might have been set up before pluto was run or -perhaps by some agent not known to pluto. -
route-host or route-client
-is run when bringing up a connection for a new peer client subnet -(even if prepare-host or prepare-client was run). The -command should install a suitable route. Routing decisions are based -only on the destination (peer's client) subnet address, unlike eroutes -which discriminate based on source too. -
unroute-host or unroute-client
-is run when bringing down the last connection for a particular peer -client subnet. It should undo what the route-host or route-client -did. -
up-host or up-client
-is run when bringing up a tunnel eroute with a pair of client subnets -that does not already have a tunnel eroute. -This command should install firewall rules as appropriate. -It is generally a good idea to allow IKE messages (UDP port 500) -travel between the hosts. -
down-host or down-client
-is run when bringing down the eroute for a pair of client subnets. -This command should delete firewall rules as appropriate. Note that -there may remain some inbound IPsec SAs with these client subnets. -
-

- -The script is passed a large number of environment variables to specify -what needs to be done. -

-
PLUTO_VERSION
-indicates what version of this interface is being used. This document -describes version 1.1. This is upwardly compatible with version 1.0. -
PLUTO_VERB
-specifies the name of the operation to be performed -(prepare-host,r prepare-client, -up-host, up-client, -down-host, or down-client). If the address family for -security gateway to security gateway communications is IPv6, then -a suffix of -v6 is added to the verb. -
PLUTO_CONNECTION
-is the name of the connection for which we are routing. -
PLUTO_NEXT_HOP
-is the next hop to which packets bound for the peer must be sent. -
PLUTO_INTERFACE
-is the name of the ipsec interface to be used. -
PLUTO_ME
-is the IP address of our host. -
PLUTO_MY_CLIENT
-is the IP address / count of our client subnet. -If the client is just the host, this will be the host's own IP address / max -(where max is 32 for IPv4 and 128 for IPv6). -
PLUTO_MY_CLIENT_NET
-is the IP address of our client net. -If the client is just the host, this will be the host's own IP address. -
PLUTO_MY_CLIENT_MASK
-is the mask for our client net. -If the client is just the host, this will be 255.255.255.255. -
PLUTO_PEER
-is the IP address of our peer. -
PLUTO_PEER_CLIENT
-is the IP address / count of the peer's client subnet. -If the client is just the peer, this will be the peer's own IP address / max -(where max is 32 for IPv4 and 128 for IPv6). -
PLUTO_PEER_CLIENT_NET
-is the IP address of the peer's client net. -If the client is just the peer, this will be the peer's own IP address. -
PLUTO_PEER_CLIENT_MASK
-is the mask for the peer's client net. -If the client is just the peer, this will be 255.255.255.255. -
-

- -All output sent by the script to stderr or stdout is logged. The -script should return an exit status of 0 if and only if it succeeds. -

- -Pluto waits for the script to finish and will not do any other -processing while it is waiting. -The script may assume that pluto will not change anything -while the script runs. -The script should avoid doing anything that takes much time and it -should not issue any command that requires processing by pluto. -Either of these activities could be performed by a background -subprocess of the script. -  -

Rekeying

- -

- -When an SA that was initiated by pluto has only a bit of -lifetime left, -pluto will initiate the creation of a new SA. This applies to -ISAKMP and IPsec SAs. -The rekeying will be initiated when the SA's remaining lifetime is -less than the rekeymargin plus a random percentage, between 0 and -rekeyfuzz, of the rekeymargin. -

- -Similarly, when an SA that was initiated by the peer has only a bit of -lifetime left, pluto will try to initiate the creation of a -replacement. -To give preference to the initiator, this rekeying will only be initiated -when the SA's remaining lifetime is half of rekeymargin. -If rekeying is done by the responder, the roles will be reversed: the -responder for the old SA will be the initiator for the replacement. -The former initiator might also initiate rekeying, so there may -be redundant SAs created. -To avoid these complications, make sure that rekeymargin is generous. -

- -One risk of having the former responder initiate is that perhaps -none of its proposals is acceptable to the former initiator -(they have not been used in a successful negotiation). -To reduce the chances of this happening, and to prevent loss of security, -the policy settings are taken from the old SA (this is the case even if -the former initiator is initiating). -These may be stricter than those of the connection. -

- -pluto will not rekey an SA if that SA is not the most recent of its -type (IPsec or ISAKMP) for its potential connection. -This avoids creating redundant SAs. -

- -The random component in the rekeying time (rekeyfuzz) is intended to -make certain pathological patterns of rekeying unstable. If both -sides decide to rekey at the same time, twice as many SAs as necessary -are created. This could become a stable pattern without the -randomness. -

- -Another more important case occurs when a security gateway has SAs -with many other security gateways. Each of these connections might -need to be rekeyed at the same time. This would cause a high peek -requirement for resources (network bandwidth, CPU time, entropy for -random numbers). The rekeyfuzz can be used to stagger the rekeying -times. -

- -Once a new set of SAs has been negotiated, pluto will never send -traffic on a superseded one. Traffic will be accepted on an old SA -until it expires. -  -

Selecting a Connection When Responding: Road Warrior Support

- -

- -When pluto receives an initial Main Mode message, it needs to -decide which connection this message is for. It picks based solely on -the source and destination IP addresses of the message. There might -be several connections with suitable IP addresses, in which case one -of them is arbitrarily chosen. (The ISAKMP SA proposal contained in -the message could be taken into account, but it is not.) -

- -The ISAKMP SA is negotiated before the parties pass further -identifying information, so all ISAKMP SA characteristics specified in -the connection description should be the same for every connection -with the same two host IP addresses. At the moment, the only -characteristic that might differ is authentication method. -

- -Up to this point, -all configuring has presumed that the IP addresses -are known to all parties ahead of time. This will not work -when either end is mobile (or assigned a dynamic IP address for other -reasons). We call this situation ``Road Warrior''. It is fairly tricky -and has some important limitations, most of which are features of -the IKE protocol. -

- -Only the initiator may be mobile: -the initiator may have an IP number unknown to the responder. When -the responder doesn't recognize the IP address on the first Main Mode -packet, it looks for a connection with itself as one end and %any -as the other. -If it cannot find one, it refuses to negotiate. If it -does find one, it creates a temporary connection that is a duplicate -except with the %any replaced by the source IP address from the -packet; if there was no identity specified for the peer, the new IP -address will be used. -

- -When pluto is using one of these temporary connections and -needs to find the preshared secret or RSA private key in ipsec.secrets, -and and the connection specified no identity for the peer, %any -is used as its identity. After all, the real IP address was apparently -unknown to the configuration, so it is unreasonable to require that -it be used in this table. -

- -Part way into the Phase 1 (Main Mode) negotiation using one of these -temporary connection descriptions, pluto will be receive an -Identity Payload. At this point, pluto checks for a more -appropriate connection, one with an identity for the peer that matches -the payload but which would use the same keys so-far used for -authentication. If it finds one, it will switch to using this better -connection (or a temporary derived from this, if it has %any -for the peer's IP address). It may even turn out that no connection -matches the newly discovered identity, including the current connection; -if so, pluto terminates negotiation. -

- -Unfortunately, if preshared secret authentication is being used, the -Identity Payload is encrypted using this secret, so the secret must be -selected by the responder without knowing this payload. This -limits there to being at most one preshared secret for all Road Warrior -systems connecting to a host. RSA Signature authentications does not -require that the responder know how to select the initiator's public key -until after the initiator's Identity Payload is decoded (using the -responder's private key, so that must be preselected). -

- -When pluto is responding to a Quick Mode negotiation via one of these -temporary connection descriptions, it may well find that the subnets -specified by the initiator don't match those in the temporary -connection description. If so, it will look for a connection with -matching subnets, its own host address, a peer address of %any -and matching identities. -If it finds one, a new temporary connection is derived from this one -and used for the Quick Mode negotiation of IPsec SAs. If it does not -find one, pluto terminates negotiation. -

- -Be sure to specify an appropriate nexthop for the responder -to send a message to the initiator: pluto has no way of guessing -it (if forwarding isn't required, use an explicit %direct as the nexthop -and the IP address of the initiator will be filled in; the obsolete -notation 0.0.0.0 is still accepted). -

- -pluto has no special provision for the initiator side. The current -(possibly dynamic) IP address and nexthop must be used in defining -connections. These must be -properly configured each time the initiator's IP address changes. -pluto has no mechanism to do this automatically. -

- -Although we call this Road Warrior Support, it could also be used to -support encrypted connections with anonymous initiators. The -responder's organization could announce the preshared secret that would be used -with unrecognized initiators and let anyone connect. Of course the initiator's -identity would not be authenticated. -

- -If any Road Warrior connections are supported, pluto cannot -reject an exchange initiated by an unknown host until it has -determined that the secret is not shared or the signature is invalid. -This must await the -third Main Mode message from the initiator. If no Road Warrior -connection is supported, the first message from an unknown source -would be rejected. This has implications for ease of debugging -configurations and for denial of service attacks. -

- -Although a Road Warrior connection must be initiated by the mobile -side, the other side can and will rekey using the temporary connection -it has created. If the Road Warrior wishes to be able to disconnect, -it is probably wise to set --keyingtries to 1 in the -connection on the non-mobile side to prevent it trying to rekey the -connection. Unfortunately, there is no mechanism to unroute the -connection automatically. -  -

Debugging

- -

- -pluto accepts several optional arguments, useful mostly for debugging. -Except for --interface, each should appear at most once. -

-
--interface interfacename
-specifies that the named real public network interface should be considered. -The interface name specified should not be ipsecN. -If the option doesn't appear, all interfaces are considered. -To specify several interfaces, use the option once for each. -One use of this option is to specify which interface should be used -when two or more share the same IP address. -
--ikeport port-number
-changes the UDP port that pluto will use -(default, specified by IANA: 500) -
--ctlbase path
-basename for control files. -path.ctl is the socket through which whack communicates with -pluto. -path.pid is the lockfile to prevent multiple pluto instances. -The default is /var/run/pluto). -
--secretsfile file
-specifies the file for authentication secrets -(default: /etc/ipsec.secrets). -This name is subject to ``globbing'' as in sh(1), -so every file with a matching name is processed. -Quoting is generally needed to prevent the shell from doing the globbing. -
--adns pathname
-
--lwdnsq pathname
-specifies where to find pluto's helper program for asynchronous DNS lookup. -pluto can be built to use one of two helper programs: _pluto_adns -or lwdnsq. You must use the program for which it was built. -By default, pluto will look for the program in -$IPSEC_DIR (if that environment variable is defined) or, failing that, -in the same directory as pluto. -
--nofork
-disable ``daemon fork'' (default is to fork). In addition, after the -lock file and control socket are created, print the line ``Pluto -initialized'' to standard out. -
--noklips
-don't actually implement negotiated IPsec SAs -
--uniqueids
-if this option has been selected, whenever a new ISAKMP SA is -established, any connection with the same Peer ID but a different -Peer IP address is unoriented (causing all its SAs to be deleted). -This helps clean up dangling SAs when a connection is lost and -then regained at another IP address. -
--stderrlog
-log goes to standard out {default is to use syslogd(8)) -
-

- -For example -

-
pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500 --nofork --noklips --stderrlog
-
-

- -lets one test pluto without using the superuser account. -

- -pluto is willing to produce a prodigious amount of debugging -information. To do so, it must be compiled with -DDEBUG. There are -several classes of debugging output, and pluto may be directed to -produce a selection of them. All lines of -debugging output are prefixed with ``| '' to distinguish them from error -messages. -

- -When pluto is invoked, it may be given arguments to specify -which classes to output. The current options are: -

-
--debug-raw
-show the raw bytes of messages -
--debug-crypt
-show the encryption and decryption of messages -
--debug-parsing
-show the structure of input messages -
--debug-emitting
-show the structure of output messages -
--debug-control
-show pluto's decision making -
--debug-lifecycle
-[this option is temporary] log more detail of lifecycle of SAs -
--debug-klips
-show pluto's interaction with KLIPS -
--debug-dns
-show pluto's interaction with DNS for KEY and TXT records -
--debug-oppo
-show why pluto didn't find a suitable DNS TXT record to authorize opportunistic initiation -
--debug-all
-all of the above -
--debug-private
-allow debugging output with private keys. -
--debug-none
-none of the above -
-

- -The debug form of the -whack command will change the selection in a running -pluto. -If a connection name is specified, the flags are added whenever -pluto has identified that it is dealing with that connection. -Unfortunately, this is often part way into the operation being observed. -

- -For example, to start a pluto with a display of the structure of input -and output: -

-
-pluto --debug-emitting --debug-parsing -
-

- -To later change this pluto to only display raw bytes: -

-
-whack --debug-raw -
-

- -For testing, SSH's IKE test page is quite useful: -

-
-http://isakmp-test.ssh.fi/ -
-

- -Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA -is established. This allows future IPsec SA's to be negotiated -directly. If one of the IKEs is restarted, the other may try to use -the ISAKMP SA but the new IKE won't know about it. This can lead to -much confusion. pluto is not yet smart enough to get out of such a -mess. -  -

Pluto's Behaviour When Things Go Wrong

- -

- -When pluto doesn't understand or accept a message, it just -ignores the message. It is not yet capable of communicating the -problem to the other IKE daemon (in the future it might use -Notifications to accomplish this in many cases). It does log a diagnostic. -

- -When pluto gets no response from a message, it resends the same -message (a message will be sent at most three times). This is -appropriate: UDP is unreliable. -

- -When pluto gets a message that it has already seen, there are many -cases when it notices and discards it. This too is appropriate for UDP. -

- -Combine these three rules, and you can explain many apparently -mysterious behaviours. In a pluto log, retrying isn't usually the -interesting event. The critical thing is either earlier (pluto -got a message which it didn't like and so ignored, so it was still -awaiting an acceptable message and got impatient) or on the other -system (pluto didn't send a reply because it wasn't happy with -the previous message). -  -

Notes

- -

- -If pluto is compiled without -DKLIPS, it negotiates Security -Associations but never ask the kernel to put them in place and never -makes routing changes. This allows pluto to be tested on systems -without KLIPS, but makes it rather useless. -

- -Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA. -The IKE protocol lets the destination of the SA choose the SPI. -The range 0 to 0xFF is reserved for IANA. -Pluto also avoids choosing an SPI in the range 0x100 to 0xFFF, -leaving these SPIs free for manual keying. -Remember that the peer, if not pluto, may well chose -SPIs in this range. -  -

Policies

- -

- -This catalogue of policies may be of use when trying to configure -Pluto and another IKE implementation to interoperate. -

- -In Phase 1, only Main Mode is supported. We are not sure that -Aggressive Mode is secure. For one thing, it does not support -identity protection. It may allow more severe Denial Of Service -attacks. -

- -No Informational Exchanges are supported. These are optional and -since their delivery is not assured, they must not matter. -It is the case that some IKE implementations won't interoperate -without Informational Exchanges, but we feel they are broken. -

- -No Informational Payloads are supported. These are optional, but -useful. It is of concern that these payloads are not authenticated in -Phase 1, nor in those Phase 2 messages authenticated with HASH(3). -

-
*
-Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) -are supported. -Group MODP768 (1) is not supported because it is too weak. -
*
-Host authetication can be done by RSA Signatures or Pre-Shared -Secrets. -
*
-3DES CBC (Cypher Block Chaining mode) is the only encryption -supported, both for ISAKMP SAs and IPSEC SAs. -
*
-MD5 and SHA1 hashing are supported for packet authentication in both -kinds of SAs. -
*
-The ESP, AH, or AH plus ESP are supported. If, and only if, AH and -ESP are combined, the ESP need not have its own authentication -component. The selection is controlled by the --encrypt and ---authenticate flags. -
*
-Each of these may be combined with IPCOMP Deflate compression, -but only if the potential connection specifies compression and only -if KLIPS is configured with IPCOMP support. -
*
-The IPSEC SAs may be tunnel or transport mode, where appropriate. -The --tunnel flag controls this when pluto is initiating. -
*
-When responding to an ISAKMP SA proposal, the maximum acceptable -lifetime is eight hours. The default is one hour. There is no -minimum. The --ikelifetime flag controls this when pluto -is initiating. -
*
-When responding to an IPSEC SA proposal, the maximum acceptable -lifetime is one day. The default is eight hours. There is no -minimum. The --ipseclifetime flag controls this when pluto -is initiating. -
*
-PFS is acceptable, and will be proposed if the --pfs flag was -specified. The DH group proposed will be the same as negotiated for -Phase 1. -
-  -

SIGNALS

- -

- -Pluto responds to SIGHUP by issuing a suggestion that ``whack ---listen'' might have been intended. -

- -Pluto exits when it recieves SIGTERM. -  -

EXIT STATUS

- -

- -pluto normally forks a daemon process, so the exit status is -normally a very preliminary result. -

-
0
-means that all is OK so far. -
1
-means that something was wrong. -
10
-means that the lock file already exists. -
-

- -If whack detects a problem, it will return an exit status of 1. -If it received progress messages from pluto, it returns as status -the value of the numeric prefix from the last such message -that was not a message sent to syslog or a comment -(but the prefix for success is treated as 0). -Otherwise, the exit status is 0. -  -

FILES

- -/var/run/pluto.pid -
- -/var/run/pluto.ctl -
- -/etc/ipsec.secrets -
- -$IPSEC_LIBDIR/_pluto_adns -
- -$IPSEC_EXECDIR/lwdnsq -
- -/dev/urandom -  -

ENVIRONMENT

- -IPSEC_LIBDIR -
- -IPSEC_EXECDIR -
- -IPSECmyid -  -

SEE ALSO

- -

- -The rest of the FreeS/WAN distribution, in particular ipsec(8). -

- -ipsec_auto(8) is designed to make using pluto more pleasant. -Use it! -

- -ipsec.secrets(5) - -describes the format of the secrets file. -

- -ipsec_atoaddr(3), part of the FreeS/WAN distribution, describes the -forms that IP addresses may take. -ipsec_atosubnet(3), part of the FreeS/WAN distribution, describes the -forms that subnet specifications. -

- -For more information on IPsec, the mailing list, and the relevant -documents, see: -

-
- -http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html - -
-

- -At the time of writing, the most relevant IETF RFCs are: -

-
-RFC2409 The Internet Key Exchange (IKE) -
-RFC2408 Internet Security Association and Key Management Protocol (ISAKMP) -
-RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP -
-

- -The FreeS/WAN web site <htp://www.freeswan.org> -and the mailing lists described there. -  -

HISTORY

- -This code is released under the GPL terms. -See the accompanying file COPYING-2.0 for more details. -The GPL does NOT apply to those pieces of code written by others -which are included in this distribution, except as noted by the -individual authors. -

- -This software was originally written -for the FreeS/WAN project -<http://www.freeswan.org> -by Angelos D. Keromytis -(angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece. -Thanks go to John Ioannidis for his help. -

- -It is currently (2000) -being developed and maintained by D. Hugh Redelmeier -(hugh@mimosa.com), in Canada. The regulations of Greece and Canada -allow us to make the code freely redistributable. -

- -Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial -version of the code supporting PFS. -

- -Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion -<ponion@srd.bt.co.uk> added the PFKEY2 support. -

- -We gratefully acknowledge that we use parts of Eric Young's libdes -package; see ../libdes/COPYRIGHT. -  -

BUGS

- -pluto - -is a work-in-progress. It currently has many limitations. -For example, it ignores notification messages that it receives, and -it generates only Delete Notifications and those only for IPSEC SAs. -

- -pluto does not support the Commit Flag. -The Commit Flag is a bad feature of the IKE protocol. -It isn't protected -- neither encrypted nor authenticated. -A man in the middle could turn it on, leading to DoS. -We just ignore it, with a warning. -This should let us interoperate with -implementations that insist on it, with minor damage. -

- -pluto does not check that the SA returned by the Responder -is actually one that was proposed. It only checks that the SA is -acceptable. The difference is not large, but can show up in attributes -such as SA lifetime. -

- -There is no good way for a connection to be automatically terminated. -This is a problem for Road Warrior and Opportunistic connections. -The --dontrekey option does prevent the SAs from -being rekeyed on expiry. -Additonally, if a Road Warrior connection has a client subnet with a fixed IP -address, a negotiation with that subnet will cause any other -connection instantiations with that same subnet to be unoriented -(deleted, in effect). -See also the --uniqueids option for an extension of this. -

- -When pluto sends a message to a peer that has disappeared, -pluto receives incomplete information from the kernel, so it -logs the unsatisfactory message ``some IKE message we sent has been -rejected with ECONNREFUSED (kernel supplied no details)''. John -Denker suggests that this command is useful for tracking down the -source of these problems: -
- -       tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0
-
- -Substitute your public interface for eth0 if it is different. -

- -The word ``authenticate'' is used for two different features. We must -authenticate each IKE peer to the other. This is an important task of -Phase 1. Each packet must be authenticated, both in IKE and in IPsec, -and the method for IPsec is negotiated as an AH SA or part of an ESP SA. -Unfortunately, the protocol has no mechanism for authenticating the Phase 2 -identities. -

- -Bugs should be reported to the <users@lists.freeswan.org> mailing list. -Caution: we cannot accept -actual code from US residents, or even US citizens living outside the -US, because that would bring FreeS/WAN under US export law. Some -other countries cause similar problems. In general, we would prefer -that you send detailed problem reports rather than code: we want -FreeS/WAN to be unquestionably freely exportable, which means being -very careful about where the code comes from, and for a small bug fix, -that is often more time-consuming than just reinventing the fix -ourselves. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
-
IKE's Job
-
Pluto
-
Before Running Pluto
-
Setting up KLIPS for pluto
-
ipsec.secrets file
-
Running Pluto
-
Pluto's Internal State
-
Using Whack
-
Examples
-
The updown command
-
Rekeying
-
Selecting a Connection When Responding: Road Warrior Support
-
Debugging
-
Pluto's Behaviour When Things Go Wrong
-
Notes
-
Policies
-
-
SIGNALS
-
EXIT STATUS
-
FILES
-
ENVIRONMENT
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_portof.3.html b/doc/manpage.d/ipsec_portof.3.html deleted file mode 100644 index 3965ca62d..000000000 --- a/doc/manpage.d/ipsec_portof.3.html +++ /dev/null @@ -1,143 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PORTOF - -

IPSEC_PORTOF

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec portof - get port field of an ip_address -
- -ipsec setportof - set port field of an ip_address -
- -ipsec sockaddrof - get pointer to internal sockaddr of an ip_address -
- -ipsec sockaddrlenof - get length of internal sockaddr of an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int portof(const ip_address *src); - -
- -void setportof(int port, ip_address *dst); - -
- -struct sockaddr *sockaddrof(ip_address *src); - -
- -size_t sockaddrlenof(const ip_address *src); - -  -

DESCRIPTION

- -The -<freeswan.h> - -internal type -ip_address - -contains one of the -sockaddr - -types internally. -Reliance on this feature is discouraged, -but it may occasionally be necessary. -These functions provide low-level tools for this purpose. -

- -Portof - -and -setportof - -respectively read and write the port-number field of the internal -sockaddr. - -The values are in network byte order. -

- -Sockaddrof - -returns a pointer to the internal -sockaddr, - -for passing to other functions. -

- -Sockaddrlenof - -reports the size of the internal -sockaddr, - -for use in storage allocation. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

DIAGNOSTICS

- -Portof - -returns --1, - -sockaddrof - -returns -NULL, - -and -sockaddrlenof - -returns -0 - -if an unknown address family is found within the -ip_address. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -These functions all depend on low-level details of the -ip_address - -type, which are in principle subject to change. -Avoid using them unless really necessary. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_prng.3.html b/doc/manpage.d/ipsec_prng.3.html deleted file mode 100644 index 27763a2bb..000000000 --- a/doc/manpage.d/ipsec_prng.3.html +++ /dev/null @@ -1,204 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PRNG - -

IPSEC_PRNG

-Section: C Library Functions (3)
Updated: 1 April 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec prng_init - initialize IPsec pseudorandom-number generator -
- -ipsec prng_bytes - get bytes from IPsec pseudorandom-number generator -
- -ipsec prng_final - close down IPsec pseudorandom-number generator -  -

SYNOPSIS

- -#include <freeswan.h> - -

-void prng_init(struct prng *prng, - -
-  -const unsigned char *key, size_t keylen); - -
- -void prng_bytes(struct prng *prng, char *dst, - -
-  -size_t dstlen); - -
- -unsigned long prng_count(struct prng *prng); - -
- -void prng_final(struct prng *prng); - -  -

DESCRIPTION

- -Prng_init - -initializes a crypto-quality pseudo-random-number generator from a key; -prng_bytes - -obtains pseudo-random bytes from it; -prng_count - -reports the number of bytes extracted from it to date; -prng_final - -closes it down. -It is the user's responsibility to initialize a PRNG before using it, -and not to use it again after it is closed down. -

- -Prng_init - -initializes, -or re-initializes, -the specified -prng - -from the -key, - -whose length is given by -keylen. - -The user must allocate the -struct prng - -pointed to by -prng. - -There is no particular constraint on the length of the key, -although a key longer than 256 bytes is unnecessary because -only the first 256 would be used. -Initialization requires on the order of 3000 integer operations, -independent of key length. -

- -Prng_bytes - -obtains -dstlen - -pseudo-random bytes from the PRNG and puts them in -buf. - -This is quite fast, -on the order of 10 integer operations per byte. -

- -Prng_count - -reports the number of bytes obtained from the PRNG -since it was (last) initialized. -

- -Prng_final - -closes down a PRNG by -zeroing its internal memory, -obliterating all trace of the state used to generate its previous output. -This requires on the order of 250 integer operations. -

- -The -<freeswan.h> - -header file supplies the definition of the -prng - -structure. -Examination of its innards is discouraged, as they may change. -

- -The PRNG algorithm -used by these functions is currently identical to that of RC4(TM). -This algorithm is cryptographically strong, -sufficiently unpredictable that even a hostile observer will -have difficulty determining the next byte of output from past history, -provided it is initialized from a reasonably large key composed of -highly random bytes (see -random(4)). - -The usual run of software pseudo-random-number generators -(e.g. -random(3)) - -are -not - -cryptographically strong. -

- -The well-known attacks against RC4(TM), -e.g. as found in 802.11b's WEP encryption system, -apply only if multiple PRNGs are initialized with closely-related keys -(e.g., using a counter appended to a base key). -If such keys are used, the first few hundred pseudo-random bytes -from each PRNG should be discarded, -to give the PRNGs a chance to randomize their innards properly. -No useful attacks are known if the key is well randomized to begin with. -  -

SEE ALSO

- -random(3), random(4) -
- -Bruce Schneier, -Applied Cryptography, 2nd ed., 1996, ISBN 0-471-11709-9, -pp. 397-8. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -If an attempt is made to obtain more than 4e9 bytes -between initializations, -the PRNG will continue to work but -prng_count's - -output will stick at -4000000000. - -Fixing this would require a longer integer type and does -not seem worth the trouble, -since you should probably re-initialize before then anyway... -

- -``RC4'' is a trademark of RSA Data Security, Inc. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_prng_bytes.3.html b/doc/manpage.d/ipsec_prng_bytes.3.html deleted file mode 100644 index 27763a2bb..000000000 --- a/doc/manpage.d/ipsec_prng_bytes.3.html +++ /dev/null @@ -1,204 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PRNG - -

IPSEC_PRNG

-Section: C Library Functions (3)
Updated: 1 April 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec prng_init - initialize IPsec pseudorandom-number generator -
- -ipsec prng_bytes - get bytes from IPsec pseudorandom-number generator -
- -ipsec prng_final - close down IPsec pseudorandom-number generator -  -

SYNOPSIS

- -#include <freeswan.h> - -

-void prng_init(struct prng *prng, - -
-  -const unsigned char *key, size_t keylen); - -
- -void prng_bytes(struct prng *prng, char *dst, - -
-  -size_t dstlen); - -
- -unsigned long prng_count(struct prng *prng); - -
- -void prng_final(struct prng *prng); - -  -

DESCRIPTION

- -Prng_init - -initializes a crypto-quality pseudo-random-number generator from a key; -prng_bytes - -obtains pseudo-random bytes from it; -prng_count - -reports the number of bytes extracted from it to date; -prng_final - -closes it down. -It is the user's responsibility to initialize a PRNG before using it, -and not to use it again after it is closed down. -

- -Prng_init - -initializes, -or re-initializes, -the specified -prng - -from the -key, - -whose length is given by -keylen. - -The user must allocate the -struct prng - -pointed to by -prng. - -There is no particular constraint on the length of the key, -although a key longer than 256 bytes is unnecessary because -only the first 256 would be used. -Initialization requires on the order of 3000 integer operations, -independent of key length. -

- -Prng_bytes - -obtains -dstlen - -pseudo-random bytes from the PRNG and puts them in -buf. - -This is quite fast, -on the order of 10 integer operations per byte. -

- -Prng_count - -reports the number of bytes obtained from the PRNG -since it was (last) initialized. -

- -Prng_final - -closes down a PRNG by -zeroing its internal memory, -obliterating all trace of the state used to generate its previous output. -This requires on the order of 250 integer operations. -

- -The -<freeswan.h> - -header file supplies the definition of the -prng - -structure. -Examination of its innards is discouraged, as they may change. -

- -The PRNG algorithm -used by these functions is currently identical to that of RC4(TM). -This algorithm is cryptographically strong, -sufficiently unpredictable that even a hostile observer will -have difficulty determining the next byte of output from past history, -provided it is initialized from a reasonably large key composed of -highly random bytes (see -random(4)). - -The usual run of software pseudo-random-number generators -(e.g. -random(3)) - -are -not - -cryptographically strong. -

- -The well-known attacks against RC4(TM), -e.g. as found in 802.11b's WEP encryption system, -apply only if multiple PRNGs are initialized with closely-related keys -(e.g., using a counter appended to a base key). -If such keys are used, the first few hundred pseudo-random bytes -from each PRNG should be discarded, -to give the PRNGs a chance to randomize their innards properly. -No useful attacks are known if the key is well randomized to begin with. -  -

SEE ALSO

- -random(3), random(4) -
- -Bruce Schneier, -Applied Cryptography, 2nd ed., 1996, ISBN 0-471-11709-9, -pp. 397-8. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -If an attempt is made to obtain more than 4e9 bytes -between initializations, -the PRNG will continue to work but -prng_count's - -output will stick at -4000000000. - -Fixing this would require a longer integer type and does -not seem worth the trouble, -since you should probably re-initialize before then anyway... -

- -``RC4'' is a trademark of RSA Data Security, Inc. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_prng_final.3.html b/doc/manpage.d/ipsec_prng_final.3.html deleted file mode 100644 index 27763a2bb..000000000 --- a/doc/manpage.d/ipsec_prng_final.3.html +++ /dev/null @@ -1,204 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PRNG - -

IPSEC_PRNG

-Section: C Library Functions (3)
Updated: 1 April 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec prng_init - initialize IPsec pseudorandom-number generator -
- -ipsec prng_bytes - get bytes from IPsec pseudorandom-number generator -
- -ipsec prng_final - close down IPsec pseudorandom-number generator -  -

SYNOPSIS

- -#include <freeswan.h> - -

-void prng_init(struct prng *prng, - -
-  -const unsigned char *key, size_t keylen); - -
- -void prng_bytes(struct prng *prng, char *dst, - -
-  -size_t dstlen); - -
- -unsigned long prng_count(struct prng *prng); - -
- -void prng_final(struct prng *prng); - -  -

DESCRIPTION

- -Prng_init - -initializes a crypto-quality pseudo-random-number generator from a key; -prng_bytes - -obtains pseudo-random bytes from it; -prng_count - -reports the number of bytes extracted from it to date; -prng_final - -closes it down. -It is the user's responsibility to initialize a PRNG before using it, -and not to use it again after it is closed down. -

- -Prng_init - -initializes, -or re-initializes, -the specified -prng - -from the -key, - -whose length is given by -keylen. - -The user must allocate the -struct prng - -pointed to by -prng. - -There is no particular constraint on the length of the key, -although a key longer than 256 bytes is unnecessary because -only the first 256 would be used. -Initialization requires on the order of 3000 integer operations, -independent of key length. -

- -Prng_bytes - -obtains -dstlen - -pseudo-random bytes from the PRNG and puts them in -buf. - -This is quite fast, -on the order of 10 integer operations per byte. -

- -Prng_count - -reports the number of bytes obtained from the PRNG -since it was (last) initialized. -

- -Prng_final - -closes down a PRNG by -zeroing its internal memory, -obliterating all trace of the state used to generate its previous output. -This requires on the order of 250 integer operations. -

- -The -<freeswan.h> - -header file supplies the definition of the -prng - -structure. -Examination of its innards is discouraged, as they may change. -

- -The PRNG algorithm -used by these functions is currently identical to that of RC4(TM). -This algorithm is cryptographically strong, -sufficiently unpredictable that even a hostile observer will -have difficulty determining the next byte of output from past history, -provided it is initialized from a reasonably large key composed of -highly random bytes (see -random(4)). - -The usual run of software pseudo-random-number generators -(e.g. -random(3)) - -are -not - -cryptographically strong. -

- -The well-known attacks against RC4(TM), -e.g. as found in 802.11b's WEP encryption system, -apply only if multiple PRNGs are initialized with closely-related keys -(e.g., using a counter appended to a base key). -If such keys are used, the first few hundred pseudo-random bytes -from each PRNG should be discarded, -to give the PRNGs a chance to randomize their innards properly. -No useful attacks are known if the key is well randomized to begin with. -  -

SEE ALSO

- -random(3), random(4) -
- -Bruce Schneier, -Applied Cryptography, 2nd ed., 1996, ISBN 0-471-11709-9, -pp. 397-8. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -If an attempt is made to obtain more than 4e9 bytes -between initializations, -the PRNG will continue to work but -prng_count's - -output will stick at -4000000000. - -Fixing this would require a longer integer type and does -not seem worth the trouble, -since you should probably re-initialize before then anyway... -

- -``RC4'' is a trademark of RSA Data Security, Inc. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_prng_init.3.html b/doc/manpage.d/ipsec_prng_init.3.html deleted file mode 100644 index 27763a2bb..000000000 --- a/doc/manpage.d/ipsec_prng_init.3.html +++ /dev/null @@ -1,204 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PRNG - -

IPSEC_PRNG

-Section: C Library Functions (3)
Updated: 1 April 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec prng_init - initialize IPsec pseudorandom-number generator -
- -ipsec prng_bytes - get bytes from IPsec pseudorandom-number generator -
- -ipsec prng_final - close down IPsec pseudorandom-number generator -  -

SYNOPSIS

- -#include <freeswan.h> - -

-void prng_init(struct prng *prng, - -
-  -const unsigned char *key, size_t keylen); - -
- -void prng_bytes(struct prng *prng, char *dst, - -
-  -size_t dstlen); - -
- -unsigned long prng_count(struct prng *prng); - -
- -void prng_final(struct prng *prng); - -  -

DESCRIPTION

- -Prng_init - -initializes a crypto-quality pseudo-random-number generator from a key; -prng_bytes - -obtains pseudo-random bytes from it; -prng_count - -reports the number of bytes extracted from it to date; -prng_final - -closes it down. -It is the user's responsibility to initialize a PRNG before using it, -and not to use it again after it is closed down. -

- -Prng_init - -initializes, -or re-initializes, -the specified -prng - -from the -key, - -whose length is given by -keylen. - -The user must allocate the -struct prng - -pointed to by -prng. - -There is no particular constraint on the length of the key, -although a key longer than 256 bytes is unnecessary because -only the first 256 would be used. -Initialization requires on the order of 3000 integer operations, -independent of key length. -

- -Prng_bytes - -obtains -dstlen - -pseudo-random bytes from the PRNG and puts them in -buf. - -This is quite fast, -on the order of 10 integer operations per byte. -

- -Prng_count - -reports the number of bytes obtained from the PRNG -since it was (last) initialized. -

- -Prng_final - -closes down a PRNG by -zeroing its internal memory, -obliterating all trace of the state used to generate its previous output. -This requires on the order of 250 integer operations. -

- -The -<freeswan.h> - -header file supplies the definition of the -prng - -structure. -Examination of its innards is discouraged, as they may change. -

- -The PRNG algorithm -used by these functions is currently identical to that of RC4(TM). -This algorithm is cryptographically strong, -sufficiently unpredictable that even a hostile observer will -have difficulty determining the next byte of output from past history, -provided it is initialized from a reasonably large key composed of -highly random bytes (see -random(4)). - -The usual run of software pseudo-random-number generators -(e.g. -random(3)) - -are -not - -cryptographically strong. -

- -The well-known attacks against RC4(TM), -e.g. as found in 802.11b's WEP encryption system, -apply only if multiple PRNGs are initialized with closely-related keys -(e.g., using a counter appended to a base key). -If such keys are used, the first few hundred pseudo-random bytes -from each PRNG should be discarded, -to give the PRNGs a chance to randomize their innards properly. -No useful attacks are known if the key is well randomized to begin with. -  -

SEE ALSO

- -random(3), random(4) -
- -Bruce Schneier, -Applied Cryptography, 2nd ed., 1996, ISBN 0-471-11709-9, -pp. 397-8. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -If an attempt is made to obtain more than 4e9 bytes -between initializations, -the PRNG will continue to work but -prng_count's - -output will stick at -4000000000. - -Fixing this would require a longer integer type and does -not seem worth the trouble, -since you should probably re-initialize before then anyway... -

- -``RC4'' is a trademark of RSA Data Security, Inc. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ranbits.8.html b/doc/manpage.d/ipsec_ranbits.8.html deleted file mode 100644 index 036b2a351..000000000 --- a/doc/manpage.d/ipsec_ranbits.8.html +++ /dev/null @@ -1,147 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_RANBITS - -

IPSEC_RANBITS

-Section: Maintenance Commands (8)
Updated: 22 Aug 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ranbits - generate random bits in ASCII form -  -

SYNOPSIS

- -ipsec - -ranbits - -[ ---quick - -] [ ---continuous - -] [ ---bytes - -] nbits -  -

DESCRIPTION

- -Ranbits - -obtains -nbits - -(rounded up to the nearest byte) -high-quality random bits from -random(4), - -and emits them on standard output as an ASCII string. -The default output format is -datatot(3) - -h - -format: -lowercase hexadecimal with a -0x - -prefix and an underscore every 32 bits. -

- -The ---quick - -option produces quick-and-dirty random bits: -instead of using the high-quality random bits from -/dev/random, - -which may take some time to supply the necessary bits if -nbits - -is large, -ranbits - -uses -/dev/urandom, - -which yields prompt results but lower-quality randomness. -

- -The ---continuous - -option uses -datatot(3) - -x - -output format, like -h - -but without the underscores. -

- -The ---bytes - -option causes -nbits - -to be interpreted as a byte count rather than a bit count. -  -

FILES

- -/dev/random, /dev/urandom -  -

SEE ALSO

- -ipsec_datatot(3), random(4) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -There is an internal limit on -nbits, - -currently 20000. -

- -Without ---quick, - -ranbits's - -run time is difficult to predict. -A request for a large number of bits, -at a time when the system's entropy pool is low on randomness, -may take quite a while to satisfy. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_rangetoa.3.html b/doc/manpage.d/ipsec_rangetoa.3.html deleted file mode 100644 index 3bacd5943..000000000 --- a/doc/manpage.d/ipsec_rangetoa.3.html +++ /dev/null @@ -1,294 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOASR - -

IPSEC_ATOASR

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoasr - convert ASCII to Internet address, subnet, or range -
- -ipsec rangetoa - convert Internet address range to ASCII -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoasr(const char *src, size_t srclen, - -
-  -char *type, struct in_addr *addrs); - -
- -size_t rangetoa(struct in_addr *addrs, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; -there is no current equivalent, -because so far they have not proved useful. -

- -Atoasr - -converts an ASCII address, subnet, or address range -into a suitable combination of binary addresses -(in network byte order). -Rangetoa - -converts an address range back into ASCII, -using dotted-decimal form for the addresses -(the other reverse conversions are handled by -ipsec_addrtoa(3) - -and -ipsec_subnettoa(3)). - -

- -A single address can be any form acceptable to -ipsec_atoaddr(3): - -dotted decimal, DNS name, or hexadecimal number. -A subnet -specification uses the form network/mask -interpreted by -ipsec_atosubnet(3). - -

- -An address range is two -ipsec_atoaddr(3) - -addresses separated by a -... - -delimiter. -If there are four dots rather than three, the first is taken as -part of the begin address, -e.g. for a complete DNS name which ends with -. - -to suppress completion attempts. -The begin address of a range must be -less than or equal to the end address. -

- -The -srclen - -parameter of -atoasr - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -type - -parameter of -atoasr - -must point to a -char - -variable used to record which form was found. -The -addrs - -parameter must point to a two-element array of -struct in_addr - -which receives the results. -The values stored into -*type, - -and the corresponding values in the array, are: -

- - - -   *typeaddrs[0]addrs[1]
-

-address'a'address-
-
- -subnet 's'networkmask
-
- -range  'r'beginend
-

- -The -dstlen - -parameter of -rangetoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant, -RANGETOA_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -rangetoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available. -This parameter is a hedge against future needs. -

- -Atoasr - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Rangetoa - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -ipsec_atoaddr(3), ipsec_atosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoasr - -are: -empty input; -error in -ipsec_atoaddr(3) - -or -ipsec_atosubnet(3) - -during conversion; -begin address of range exceeds end address. -

- -Fatal errors in -rangetoa - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoasr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_rangetosubnet.3.html b/doc/manpage.d/ipsec_rangetosubnet.3.html deleted file mode 100644 index 9e03244ea..000000000 --- a/doc/manpage.d/ipsec_rangetosubnet.3.html +++ /dev/null @@ -1,116 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_RANGETOSUBNET - -

IPSEC_RANGETOSUBNET

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec rangetosubnet - convert address range to subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *rangetosubnet(const ip_address *start, - -
-  -const ip_address *stop, ip_subnet *dst); - -  -

DESCRIPTION

- -Rangetosubnet - -accepts two IP addresses which define an address range, -from -start - -to -stop - -inclusive, -and converts this to a subnet if possible. -The addresses must both be IPv4 or both be IPv6, -and the address family of the resulting subnet is the same. -

- -Rangetosubnet - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -ipsec_initsubnet(3), ipsec_ttosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -rangetosubnet - -are: -mixed address families; -unknown address family; -start - -and -stop - -do not define a subnet. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = rangetosubnet( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_rsasigkey.8.html b/doc/manpage.d/ipsec_rsasigkey.8.html deleted file mode 100644 index 3173a9f13..000000000 --- a/doc/manpage.d/ipsec_rsasigkey.8.html +++ /dev/null @@ -1,401 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_RSASIGKEY - -

IPSEC_RSASIGKEY

-Section: Maintenance Commands (8)
Updated: 22 July 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec rsasigkey - generate RSA signature key -  -

SYNOPSIS

- -ipsec - -rsasigkey - -[ ---verbose - -] [ ---random - -filename -] -\ - -
- -   [ ---rounds - -nr -] [ ---hostname - -host ] [ ---noopt - -] nbits -
- -ipsec - -rsasigkey - -[ ---verbose - -] [ ---hostname - -host ] -\ - -
- -    -[ ---noopt - -] ---oldkey - -file -  -

DESCRIPTION

- -Rsasigkey - -generates an RSA public/private key pair, -suitable for digital signatures, -of (exactly) -nbits - -bits (that is, two primes each of exactly -nbits/2 - -bits, -and related numbers) -and emits it on standard output as ASCII (mostly hex) data. -nbits - -must be a multiple of 16. -

- -The public exponent is forced to the value -3, - -which has important speed advantages for signature checking. -Beware that the resulting keys have known weaknesses as encryption keys -and should not be used for that purpose. -

- -The ---verbose - -option makes -rsasigkey - -give a running commentary on standard error. -By default, it works in silence until it is ready to generate output. -

- -The ---random - -option specifies a source for random bits. -The default is -/dev/random - -(see -random(4)). - -Normally, -rsasigkey - -reads exactly -nbits - -random bits from the source; -in extremely-rare circumstances it may need more. -

- -The ---rounds - -option specifies the number of rounds to be done by the -mpz_probab_prime_p - -probabilistic primality checker. -The default, 30, is fairly rigorous and should not normally -have to be overridden. -

- -The ---hostname - -option specifies what host name to use in -the first line of the output (see below); -the default is what -gethostname(2) - -returns. -

- -The ---noopt - -option suppresses an optimization of the private key -(to be precise, setting of the decryption exponent to -lcm(p-1,q-1) - -rather than -(p-1)*(q-1)) - -which speeds up operations on it slightly -but can cause it to flunk a validity check in old RSA implementations -(notably, obsolete versions of -ipsec_pluto(8)). - -

- -The ---oldkey - -option specifies that rather than generate a new key, -rsasigkey - -should read an old key from the -file - -(the name -- - -means ``standard input'') -and use that to generate its output. -Input lines which do not look like -rsasigkey - -output are silently ignored. -This permits updating old keys to the current format. -

- -The output format looks like this (with long numbers trimmed down -for clarity): -

- - -

-        # RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
-        # for signatures only, UNSAFE FOR ENCRYPTION
-        #pubkey=0sAQOF8tZ2NZt...Y1P+buFuFn/
-        Modulus: 0xcc2a86fcf440...cf1011abb82d1
-        PublicExponent: 0x03
-        # everything after this point is secret
-        PrivateExponent: 0x881c59fdf8...ab05c8c77d23
-        Prime1: 0xf49fd1f779...46504c7bf3
-        Prime2: 0xd5a9108453...321d43cb2b
-        Exponent1: 0xa31536a4fb...536d98adda7f7
-        Exponent2: 0x8e70b5ad8d...9142168d7dcc7
-        Coefficient: 0xafb761d001...0c13e98d98
-
- -

- -The first (comment) line, -indicating the nature and date of the key, -and giving a host name, -is used by -ipsec_showhostkey(8) - -when generating some forms of key output. -

- -The commented-out -pubkey= - -line contains the public key---the public exponent and the modulus---combined -in approximately RFC 2537 format -(the one deviation is that the combined value is given with a -0s - -prefix, rather than in unadorned base-64), -suitable for use in the -ipsec.conf - -file. -

- -The -Modulus, - -PublicExponent, - -and -PrivateExponent - -lines give the basic signing and verification data. -

- -The -Prime1 - -and -Prime2 - -lines give the primes themselves (aka -p - -and -q), - -largest first. -The -Exponent1 - -and -Exponent2 - -lines give -the private exponent mod -p-1 - -and -q-1 - -respectively. -The -Coefficient - -line gives the Chinese Remainder Theorem coefficient, -which is the inverse of -q, - -mod -p. - -These additional numbers (which must all be kept as secret as the -private exponent) are precomputed aids to rapid signature generation. -

- -No attempt is made to break long lines. -

- -The US patent on the RSA algorithm expired 20 Sept 2000. -  -

EXAMPLES

- -
-
ipsec rsasigkey --verbose 2192 >mykey - -
-generates a 2192-bit signature key and puts it in the file -mykey, - -with running commentary on standard error. -The file contents can be inserted verbatim into a suitable entry in the -ipsec.secrets - -file (see -ipsec.secrets(5)), - -and the public key can then be extracted and edited into the -ipsec.conf - -file (see -ipsec.conf(5)). - -
ipsec rsasigkey --verbose --oldkey oldie >latest - -
-takes the old signature key from file -oldie - -and puts a version in the current format into the file -latest, - -with running commentary on standard error. -
-  -

FILES

- -/dev/random -  -

SEE ALSO

- -random(4), ipsec_showhostkey(8) -
- -Applied Cryptography, 2nd. ed., by Bruce Schneier, Wiley 1996. -
- -RFCs 2537, 2313. -
- -GNU MP, the GNU multiple precision arithmetic library, edition 2.0.2, -by Torbj Granlund. -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -There is an internal limit on -nbits, - -currently 20000. -

- -Rsasigkey's - -run time is difficult to predict, -since -/dev/random - -output can be arbitrarily delayed if -the system's entropy pool is low on randomness, -and the time taken by the search for primes is also somewhat unpredictable. -A reasonably typical time for a 1024-bit key on a quiet 200MHz Pentium MMX -with plenty of randomness available is 20 seconds, -almost all of it in the prime searches. -Generating a 2192-bit key on the same system usually takes several minutes. -A 4096-bit key took an hour and a half of CPU time. -

- -The ---oldkey - -option does not check its input format as rigorously as it might. -Corrupted -rsasigkey - -output may confuse it. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_sameaddr.3.html b/doc/manpage.d/ipsec_sameaddr.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_sameaddr.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_sameaddrtype.3.html b/doc/manpage.d/ipsec_sameaddrtype.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_sameaddrtype.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_samesaid.3.html b/doc/manpage.d/ipsec_samesaid.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_samesaid.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_samesubnet.3.html b/doc/manpage.d/ipsec_samesubnet.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_samesubnet.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_samesubnettype.3.html b/doc/manpage.d/ipsec_samesubnettype.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_samesubnettype.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_satoa.3.html b/doc/manpage.d/ipsec_satoa.3.html deleted file mode 100644 index 2b2c7425c..000000000 --- a/doc/manpage.d/ipsec_satoa.3.html +++ /dev/null @@ -1,347 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOSA - -

IPSEC_ATOSA

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atosa, satoa - convert IPsec Security Association IDs to and from ASCII -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atosa(const char *src, size_t srclen, - -
-  -struct sa_id *sa); - -
- -size_t satoa(struct sa_id sa, int format, - -
-  -char *dst, size_t dstlen); - -

-struct sa_id { - -
-  -struct in_addr dst; - -
-  -ipsec_spi_t spi; - -
-  -int proto; - -
- -}; - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttosa(3) - -for their replacements. -

- -Atosa - -converts an ASCII Security Association (SA) specifier into an -sa_id - -structure (containing -a destination-host address -in network byte order, -an SPI number in network byte order, and -a protocol code). -Satoa - -does the reverse conversion, back to an ASCII SA specifier. -

- -An SA is specified in ASCII with a mail-like syntax, e.g. -esp507@1.2.3.4. - -An SA specifier contains -a protocol prefix (currently -ah, - -esp, - -or -tun), - -an unsigned integer SPI number, -and an IP address. -The SPI number can be decimal or hexadecimal -(with -0x - -prefix), as accepted by -ipsec_atoul(3). - -The IP address can be any form accepted by -ipsec_atoaddr(3), - -e.g. dotted-decimal address or DNS name. -

- -As a special case, the SA specifier -%passthrough - -signifies the special SA used to indicate that packets should be -passed through unaltered. -(At present, this is a synonym for -tun0x0@0.0.0.0, - -but that is subject to change without notice.) -This form is known to both -atosa - -and -satoa, - -so the internal form of -%passthrough - -is never visible. -

- -The -<freeswan.h> - -header file supplies the -sa_id - -structure, as well as a data type -ipsec_spi_t - -which is an unsigned 32-bit integer. -(There is no consistency between kernel and user on what such a type -is called, hence the header hides the differences.) -

- -The protocol code uses the same numbers that IP does. -For user convenience, given the difficulty in acquiring the exact set of -protocol names used by the kernel, -<freeswan.h> - -defines the names -SA_ESP, - -SA_AH, - -and -SA_IPIP - -to have the same values as the kernel names -IPPROTO_ESP, - -IPPROTO_AH, - -and -IPPROTO_IPIP. - -

- -The -srclen - -parameter of -atosa - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -satoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant, -SATOA_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -satoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default -(currently -lowercase protocol prefix, lowercase hexadecimal SPI, dotted-decimal address). -The value -d - -causes the SPI to be generated in decimal instead. -

- -Atosa - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Satoa - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -ipsec_atoul(3), ipsec_atoaddr(3), inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atosa - -are: -empty input; -input too small to be a legal SA specifier; -no -@ - -in input; -unknown protocol prefix; -conversion error in -atoul - -or -atoaddr. - -

- -Fatal errors in -satoa - -are: -unknown format; unknown protocol code. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The -tun - -protocol code is a FreeS/WANism which may eventually disappear. -

- -The restriction of ASCII-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The ASCII-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_satot.3.html b/doc/manpage.d/ipsec_satot.3.html deleted file mode 100644 index 1e457fc24..000000000 --- a/doc/manpage.d/ipsec_satot.3.html +++ /dev/null @@ -1,453 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOSA - -

IPSEC_TTOSA

-Section: C Library Functions (3)
Updated: 26 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttosa, satot - convert IPsec Security Association IDs to and from text -
- -ipsec initsaid - initialize an SA ID -  -

SYNOPSIS

- -#include <freeswan.h> - -

-typedef struct { - -
-  -ip_address dst; - -
-  -ipsec_spi_t spi; - -
-  -int proto; - -
- -} ip_said; - -

-const char *ttosa(const char *src, size_t srclen, - -
-  -ip_said *sa); - -
- -size_t satot(const ip_said *sa, int format, - -
-  -char *dst, size_t dstlen); - -
- -void initsaid(const ip_address *addr, ipsec_spi_t spi, - -
-  -int proto, ip_said *dst); - -  -

DESCRIPTION

- -Ttosa - -converts an ASCII Security Association (SA) specifier into an -ip_said - -structure (containing -a destination-host address -in network byte order, -an SPI number in network byte order, and -a protocol code). -Satot - -does the reverse conversion, back to a text SA specifier. -Initsaid - -initializes an -ip_said - -from separate items of information. -

- -An SA is specified in text with a mail-like syntax, e.g. -esp.5a7@1.2.3.4. - -An SA specifier contains -a protocol prefix (currently -ah, - -esp, - -tun, - -comp, - -or -int), - -a single character indicating the address family -(. - -for IPv4, -: - -for IPv6), -an unsigned integer SPI number in hexadecimal (with no -0x - -prefix), -and an IP address. -The IP address can be any form accepted by -ipsec_ttoaddr(3), - -e.g. dotted-decimal IPv4 address, -colon-hex IPv6 address, -or DNS name. -

- -As a special case, the SA specifier -%passthrough4 - -or -%passthrough6 - -signifies the special SA used to indicate that packets should be -passed through unaltered. -(At present, these are synonyms for -tun.0@0.0.0.0 - -and -tun:0@:: - -respectively, -but that is subject to change without notice.) -%passthrough - -is a historical synonym for -%passthrough4. - -These forms are known to both -ttosa - -and -satot, - -so the internal representation is never visible. -

- -Similarly, the SA specifiers -%pass, - -%drop, - -%reject, - -%hold, - -%trap, - -and -%trapsubnet - -signify special ``magic'' SAs used to indicate that packets should be -passed, dropped, rejected (dropped with ICMP notification), -held, -and trapped (sent up to -ipsec_pluto(8), - -with either of two forms of -%hold - -automatically installed) -respectively. -These forms too are known to both routines, -so the internal representation of the magic SAs should never be visible. -

- -The -<freeswan.h> - -header file supplies the -ip_said - -structure, as well as a data type -ipsec_spi_t - -which is an unsigned 32-bit integer. -(There is no consistency between kernel and user on what such a type -is called, hence the header hides the differences.) -

- -The protocol code uses the same numbers that IP does. -For user convenience, given the difficulty in acquiring the exact set of -protocol names used by the kernel, -<freeswan.h> - -defines the names -SA_ESP, - -SA_AH, - -SA_IPIP, - -and -SA_COMP - -to have the same values as the kernel names -IPPROTO_ESP, - -IPPROTO_AH, - -IPPROTO_IPIP, - -and -IPPROTO_COMP. - -

- -<freeswan.h> - -also defines -SA_INT - -to have the value -61 - -(reserved by IANA for ``any host internal protocol'') -and -SPI_PASS, - -SPI_DROP, - -SPI_REJECT, - -SPI_HOLD, - -and -SPI_TRAP - -to have the values 256-260 (in host byte order) respectively. -These are used in constructing the magic SAs -(which always have address -0.0.0.0). - -

- -If -satot - -encounters an unknown protocol code, e.g. 77, -it yields output using a prefix -showing the code numerically, e.g. ``unk77''. -This form is -not - -recognized by -ttosa. - -

- -The -srclen - -parameter of -ttosa - -specifies the length of the string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -satot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -<freeswan.h> - -header file defines a constant, -SATOT_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -satot - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default -(currently -lowercase protocol prefix, lowercase hexadecimal SPI, -dotted-decimal or colon-hex address). -The value -'f' - -is similar except that the SPI is padded with -0s - -to a fixed 32-bit width, to ease aligning displayed tables. -

- -Ttosa - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Satot - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -

- -There is also, temporarily, support for some obsolete -forms of SA specifier which lack the address-family indicator. -  -

SEE ALSO

- -ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttosa - -are: -empty input; -input too small to be a legal SA specifier; -no -@ - -in input; -unknown protocol prefix; -conversion error in -ttoul - -or -ttoaddr. - -

- -Fatal errors in -satot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttosa( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_send-pr.8.html b/doc/manpage.d/ipsec_send-pr.8.html deleted file mode 100644 index 19026543a..000000000 --- a/doc/manpage.d/ipsec_send-pr.8.html +++ /dev/null @@ -1,427 +0,0 @@ -Content-type: text/html - -Manpage of SEND-PR - -

SEND-PR

-Section: User Commands (1)
Updated: xVERSIONx
Index -Return to Main Contents
- -  -

NAME

- -ipsec send-pr - send problem report (PR) to a central support site -  -

SYNOPSIS

- -ipsec send-pr - -[ -site - -] -[ --f - -problem-report - -] -[ --t - -mail-address - -] -
- - -[ --P - -] -[ --L - -] -[ --s - -severity - -] -[ --c - -address - -] -
- -[ ---request-id - -] -[ --V - -] -  -

DESCRIPTION

- -ipsec send-pr - -is a tool used to submit -problem reports - - -(PRs) to a central support site. In most cases the correct -site - -will be the default. This argument indicates the support site which -is responsible for the category of problem involved. Some sites may -use a local address as a default. -site - -values are defined by using the -aliases(5). - -

- -ipsec send-pr - -invokes an editor on a problem report template (after trying to fill -in some fields with reasonable default values). When you exit the -editor, -ipsec send-pr - -sends the completed form to the -Problem Report Management System - -(GNATS) at a central support site. At the support site, the PR -is assigned a unique number and is stored in the GNATS database -according to its category and submitter-id. GNATS automatically -replies with an acknowledgement, citing the category and the PR -number. -

- -To ensure that a PR is handled promptly, it should contain your (unique) -submitter-id and one of the available categories to identify the -problem area. (Use -`ipsec send-pr -L' - -to see a list of categories.) -

- -The -ipsec send-pr - -template at your site should already be customized with your -submitter-id (running `install-sid submitter-id' to -accomplish this is part of the installation procedures for -ipsecsend-pr). - -If this hasn't been done, see your system administrator for your -submitter-id, or request one from your support site by invoking -`ipsec send-pr --request-id'. - -If your site does not distinguish between different user sites, or if -you are not affiliated with the support site, use -`net' - -for this field. -

- -The more precise your problem description and the more complete your -information, the faster your support team can solve your problems. -  -

OPTIONS

- -
-
-f problem-report - -
-specify a file (problem-report) which already contains a -complete problem report. -ipsec send-pr - -sends the contents of the file without invoking the editor. If -the value for -problem-report - -is -`-', - -then -ipsec send-pr - -reads from standard input. -
-s severity - -
-Give the problem report the severity -severity. - -
-t mail-address - -
-Change mail address at the support site for problem reports. The -default -mail-address - -is the address used for the default -site. - -Use the -site - -argument rather than this option in nearly all cases. -
-c address - -
-Put -address - -in the -Cc: - -header of the message. -
-P - -
-print the form specified by the environment variable -PR_FORM - -on standard output. If -PR_FORM - -is not set, print the standard blank PR template. No mail is sent. -
-L - -
-print the list of available categories. No mail is sent. -
--request-id - -
-sends mail to the default support site, or -site - -if specified, with a request for your -submitter-id. - -If you are -not affiliated with -site, - -use a -submitter-id - -of -net'. - -
-V - -
-Display the -ipsec send-pr - -version number. -
-

- -Note: use -ipsec send-pr - -to submit problem reports rather than mailing them directly. Using -both the template and -ipsec send-pr - -itself will help ensure all necessary information will reach the -support site. -  -

ENVIRONMENT

- -The environment variable -EDITOR - -specifies the editor to invoke on the template. -
- -default: -vi - -

-If the environment variable -PR_FORM - -is set, then its value is used as the file name of the template for -your problem-report editing session. You can use this to start with a -partially completed form (for example, a form with the identification -fields already completed). -  -

HOW TO FILL OUT A PROBLEM REPORT

- -Problem reports have to be in a particular form so that a program can -easily manage them. Please remember the following guidelines: -
-
*
-describe only -one problem - -with each problem report. -
*
-For follow-up mail, use the same subject line as the one in the automatic -acknowledgent. It consists of category, PR number and the original synopsis -line. This allows the support site to relate several mail messages to a -particular PR and to record them automatically. -
*
-Please try to be as accurate as possible in the subject and/or synopsis line. -
*
-The subject and the synopsis line are not confidential. This is -because open-bugs lists are compiled from them. Avoid confidential -information there. -
-

- -See the GNU -Info - -file -send-pr.info - -or the document Reporting Problems With send-pr for detailed -information on reporting problems -  -

HOW TO SUBMIT TEST CASES, CODE, ETC.

- -Submit small code samples with the PR. Contact the support site for -instructions on submitting larger test cases and problematic source -code. -  -

FILES

- - - -/tmp/p$$     copy of PR used in editing session
-
- -/tmp/pf$$   copy of empty PR form, for testing purposes
-
- -/tmp/pbad$$ file for rejected PRs
-
- -@IPSEC_DIR@/send-pr.confscript to customize send-pr.
-  -

EMACS USER INTERFACE

- -An Emacs user interface for -send-pr - -with completion of field values is part of the -send-pr - -distribution (invoked with -M-x send-pr). - -See the file -send-pr.info - -or the ASCII file -INSTALL - -in the top level directory of the distribution for configuration and -installation information. The Emacs LISP template file is -send-pr-el.in - -and is installed as -send-pr.el. - -  -

INSTALLATION AND CONFIGURATION

- -See -send-pr.info - -or -INSTALL - -for installation instructions. -  -

SEE ALSO

- -Reporting Problems Using send-pr - -(also installed as the GNU Info file -send-pr.info). - -

- -gnats(l), - -query-pr(1), - -edit-pr(1), - -gnats(8), - -queue-pr(8), - -at-pr(8), - -mkcat(8), - -mkdist(8). - -  -

AUTHORS

- -Jeffrey Osier, Brendan Kehoe, Jason Merrill, Heinz G. Seidl (Cygnus -Support) -  -

COPYING

- -Copyright (c) 1992, 1993 Free Software Foundation, Inc. -

- -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. -

- -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. -

- -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the Free Software Foundation instead of in -the original English. -

-

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
OPTIONS
-
ENVIRONMENT
-
HOW TO FILL OUT A PROBLEM REPORT
-
HOW TO SUBMIT TEST CASES, CODE, ETC.
-
FILES
-
EMACS USER INTERFACE
-
INSTALLATION AND CONFIGURATION
-
SEE ALSO
-
AUTHORS
-
COPYING
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_setportof.3.html b/doc/manpage.d/ipsec_setportof.3.html deleted file mode 100644 index 3965ca62d..000000000 --- a/doc/manpage.d/ipsec_setportof.3.html +++ /dev/null @@ -1,143 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PORTOF - -

IPSEC_PORTOF

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec portof - get port field of an ip_address -
- -ipsec setportof - set port field of an ip_address -
- -ipsec sockaddrof - get pointer to internal sockaddr of an ip_address -
- -ipsec sockaddrlenof - get length of internal sockaddr of an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int portof(const ip_address *src); - -
- -void setportof(int port, ip_address *dst); - -
- -struct sockaddr *sockaddrof(ip_address *src); - -
- -size_t sockaddrlenof(const ip_address *src); - -  -

DESCRIPTION

- -The -<freeswan.h> - -internal type -ip_address - -contains one of the -sockaddr - -types internally. -Reliance on this feature is discouraged, -but it may occasionally be necessary. -These functions provide low-level tools for this purpose. -

- -Portof - -and -setportof - -respectively read and write the port-number field of the internal -sockaddr. - -The values are in network byte order. -

- -Sockaddrof - -returns a pointer to the internal -sockaddr, - -for passing to other functions. -

- -Sockaddrlenof - -reports the size of the internal -sockaddr, - -for use in storage allocation. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

DIAGNOSTICS

- -Portof - -returns --1, - -sockaddrof - -returns -NULL, - -and -sockaddrlenof - -returns -0 - -if an unknown address family is found within the -ip_address. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -These functions all depend on low-level details of the -ip_address - -type, which are in principle subject to change. -Avoid using them unless really necessary. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_setup.8.html b/doc/manpage.d/ipsec_setup.8.html deleted file mode 100644 index 7197e2b18..000000000 --- a/doc/manpage.d/ipsec_setup.8.html +++ /dev/null @@ -1,237 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SETUP - -

IPSEC_SETUP

-Section: Maintenance Commands (8)
Updated: 23 July 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec setup - control IPsec subsystem -  -

SYNOPSIS

- -ipsec - -setup - -[ ---show - -| ---showonly - -] -command -  -

DESCRIPTION

- -Setup - -controls the FreeS/WAN IPsec subsystem, -including both the Klips kernel code and the Pluto key-negotiation daemon. -(It is a synonym for the ``rc'' script for the subsystem; -the system runs the equivalent of -ipsec setup start - -at boot time, -and -ipsec setup stop - -at shutdown time, more or less.) -

- -The action taken depends on the specific -command, - -and on the contents of the -config - -setup - -section of the -IPsec configuration file (/etc/ipsec.conf, - -see -ipsec.conf(5)). - -Current -commands - -are: -

-
start - -
-start Klips and Pluto, -including setting up Klips to do crypto operations on the -interface(s) specified in the configuration file, -and (if the configuration file so specifies) -setting up manually-keyed connections and/or -asking Pluto to negotiate automatically-keyed connections -to other security gateways -
stop - -
-shut down Klips and Pluto, -including tearing down all existing crypto connections -
restart - -
-equivalent to -stop - -followed by -start - -
status - -
-report the status of the subsystem; -normally just reports -IPsec running - -and -pluto pid nnn, - -or -IPsec stopped, - -and exits with status 0, -but will go into more detail (and exit with status 1) -if something strange is found. -(An ``illicit'' Pluto is one that does not match the process ID in -Pluto's lock file; -an ``orphaned'' Pluto is one with no lock file.) -
-

- -The -stop - -operation tries to clean up properly even if assorted accidents -have occurred, -e.g. Pluto having died without removing its lock file. -If -stop - -discovers that the subsystem is (supposedly) not running, -it will complain, -but will do its cleanup anyway before exiting with status 1. -

- -Although a number of configuration-file parameters influence -setup's - -operations, the key one is the -interfaces - -parameter, which must be right or chaos will ensue. -

- -The ---show - -and ---showonly - -options cause -setup - -to display the shell commands that it would execute. ---showonly - -suppresses their execution. -Only -start, - -stop, - -and -restart - -commands recognize these flags. -  -

FILES

- - - -/etc/rc.d/init.d/ipsec         the script itself
-
- -/etc/init.d/ipsec             alternate location for the script
-
- -/etc/ipsec.conf               IPsec configuration file
-
- -/proc/sys/net/ipv4/ip_forward forwarding control
-
- -/var/run/ipsec.info           saved information
-
- -/var/run/pluto.pid            Pluto lock file
-
- -/var/run/ipsec_setup.pid      IPsec lock file
-  -

SEE ALSO

- -ipsec.conf(5), ipsec(8), ipsec_manual(8), ipsec_auto(8), route(8) -  -

DIAGNOSTICS

- -All output from the commands -start - -and -stop - -goes both to standard -output and to -syslogd(8), - -via -logger(1). - -Selected additional information is logged only to -syslogd(8). - -  -

HISTORY

- -Written for the FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -Old versions of -logger(1) - -inject spurious extra newlines onto standard output. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_showdefaults.8.html b/doc/manpage.d/ipsec_showdefaults.8.html deleted file mode 100644 index e1786dc0a..000000000 --- a/doc/manpage.d/ipsec_showdefaults.8.html +++ /dev/null @@ -1,82 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SHOWDEFAULTS - -

IPSEC_SHOWDEFAULTS

-Section: Maintenance Commands (8)
Updated: 23 Jan 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec showdefaults - show %defaultroute defaults -  -

SYNOPSIS

- -ipsec - -showdefaults - -  -

DESCRIPTION

- -Showdefaults - -outputs (on standard output) a terse description of the defaults -used by the -%defaultroute - -facilities in -ipsec_auto(8) - -and -ipsec_manual(8). - -

- -Beware that the exact output format is subject to change. -  -

DIAGNOSTICS

- -Normal exit status is 0. -If no defaults are available, -i.e. the -interfaces - -parameter in -config setup - -is not -%defaultroute, - -produces a message on standard error and exits with status 1. -  -

FILES

- -/var/run/ipsec.info -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
DIAGNOSTICS
-
FILES
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_showhostkey.8.html b/doc/manpage.d/ipsec_showhostkey.8.html deleted file mode 100644 index 90a16d5ee..000000000 --- a/doc/manpage.d/ipsec_showhostkey.8.html +++ /dev/null @@ -1,269 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SHOWHOSTKEY - -

IPSEC_SHOWHOSTKEY

-Section: Maintenance Commands (8)
Updated: 5 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec showhostkey - show host's authentication key -  -

SYNOPSIS

- -ipsec - -showhostkey - -[ ---key - -] [ ---left - -] [ ---right - -] [ ---txt - -gateway -] [ ---dhclient - -] [ ---file - -secretfile -] [ ---id - -identity -] -  -

DESCRIPTION

- -Showhostkey - -outputs (on standard output) a public key suitable for this host, -in the format specified, -using the host key information stored in -/etc/ipsec.secrets. - -In general only the super-user can run this command, -since only he can read -ipsec.secrets. - -

- -The ---txt - -option causes the output to be in opportunistic-encryption DNS TXT record -format, -with the specified -gateway - -value. -If information about how the key was generated is available, -that is provided as a DNS-file comment. -For example, ---txt 10.11.12.13 - -might give (with the key data trimmed for clarity): -

- -

-  ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
-      IN TXT  "X-IPsec-Server(10)=10.11.12.13 AQOF8tZ2...+buFuFn/"
-
- -

- -No name is supplied in the TXT record -because there are too many possibilities, -depending on how it will be used. -If the text string is longer than 255 bytes, -it is split up into multiple strings (matching the restrictions of -the DNS TXT binary format). -If any split is needed, the first split will be at the start of the key: -this increases the chances that later hand editing will work. -

- -The ---left - -and ---right - -options cause the output to be in -ipsec.conf(5) - -format, as a -leftrsasigkey - -or -rightrsasigkey - -parameter respectively. -Again, generation information is included if available. -For example, ---left - -might give (with the key data trimmed down for clarity): -

- -

-  # RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
-  leftrsasigkey=0sAQOF8tZ2...+buFuFn/
-
- -

- -The ---dhclient - -option cause the output to be suitable for inclusion in -dhclient.conf(5) - -as part of configuring WAVEsec. -See <http://www.wavesec.org>. -

- -If ---key - -is specified, -the output format is the text form of a DNS KEY record; -the host name is the one included in the key information -(or, if that is not available, -the output of -hostname --fqdn), - -with a -. - -appended. -Again, generation information is included if available. -For example (with the key data trimmed down for clarity): -

- -

-  ; RSA 2048 bits   xy.example.com   Sat Apr 15 13:53:22 2000
-  xy.example.com.   IN   KEY   0x4200 4 1 AQOF8tZ2...+buFuFn/
-
- -

- -Normally, the default key for this host -(the one with no host identities specified for it) is the one extracted. -The ---id - -option overrides this, -causing extraction of the key labeled with the specified -identity, - -if any. -The specified -identity - -must -exactly - -match the identity in the file; -in particular, the comparison is case-sensitive. -

- -The ---file - -option overrides the default for where the key information should be -found, and takes it from the specified -secretfile. - -  -

DIAGNOSTICS

- -A complaint about ``no pubkey line found'' indicates that the -host has a key but it was generated with an old version of FreeS/WAN -and does not contain the information that -showhostkey - -needs. -  -

FILES

- -/etc/ipsec.secrets -  -

SEE ALSO

- -ipsec.secrets(5), ipsec.conf(5), ipsec_rsasigkey(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Henry Spencer. -  -

BUGS

- -Arguably, -rather than just reporting the no-IN-KEY-line-found problem, -showhostkey - -should be smart enough to run the existing key through -rsasigkey - -with the ---oldkey - -option, to generate a suitable output line. -

- -The need to specify the gateway address (etc.) for ---txt - -is annoying, but there is no good way to determine it automatically. -

- -There should be a way to specify the priority value for TXT records; -currently it is hardwired to -10. - -

- -The ---id - -option assumes that the -identity - -appears on the same line as the -: RSA { - -that begins the key proper. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
DIAGNOSTICS
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_showpolicy.8.html b/doc/manpage.d/ipsec_showpolicy.8.html deleted file mode 100644 index 470c40879..000000000 --- a/doc/manpage.d/ipsec_showpolicy.8.html +++ /dev/null @@ -1,88 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SHOWPOLICY - -

IPSEC_SHOWPOLICY

-Section: Maintenance Commands (8)
Updated: 7 May 2003
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec showpolicy - dump policy of socket found as stdin -  -

SYNOPSIS

- -

- -ipsec - -showpolicy - -

- -  -

DESCRIPTION

- -showpolicy - -calls the -ipsec_policy_lookup(3) - -function on the file description which is its stdin. -

- -It then dumps the resulting query in a human readable form. -

- -This is a test program. One might run it from inetd, via: -

-
discard stream tcp nowait nobody /usr/local/libexec/ipsec/showpolicy showpolicy
-
-  -

FILES

- -/var/run/ipsecpolicy.ctl -  -

SEE ALSO

- -ipsec(8), ipsec_policy_query(3), ipsec_pluto(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Michael Richardson -  -

BUGS

- - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_sockaddrlenof.3.html b/doc/manpage.d/ipsec_sockaddrlenof.3.html deleted file mode 100644 index 3965ca62d..000000000 --- a/doc/manpage.d/ipsec_sockaddrlenof.3.html +++ /dev/null @@ -1,143 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PORTOF - -

IPSEC_PORTOF

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec portof - get port field of an ip_address -
- -ipsec setportof - set port field of an ip_address -
- -ipsec sockaddrof - get pointer to internal sockaddr of an ip_address -
- -ipsec sockaddrlenof - get length of internal sockaddr of an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int portof(const ip_address *src); - -
- -void setportof(int port, ip_address *dst); - -
- -struct sockaddr *sockaddrof(ip_address *src); - -
- -size_t sockaddrlenof(const ip_address *src); - -  -

DESCRIPTION

- -The -<freeswan.h> - -internal type -ip_address - -contains one of the -sockaddr - -types internally. -Reliance on this feature is discouraged, -but it may occasionally be necessary. -These functions provide low-level tools for this purpose. -

- -Portof - -and -setportof - -respectively read and write the port-number field of the internal -sockaddr. - -The values are in network byte order. -

- -Sockaddrof - -returns a pointer to the internal -sockaddr, - -for passing to other functions. -

- -Sockaddrlenof - -reports the size of the internal -sockaddr, - -for use in storage allocation. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

DIAGNOSTICS

- -Portof - -returns --1, - -sockaddrof - -returns -NULL, - -and -sockaddrlenof - -returns -0 - -if an unknown address family is found within the -ip_address. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -These functions all depend on low-level details of the -ip_address - -type, which are in principle subject to change. -Avoid using them unless really necessary. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_sockaddrof.3.html b/doc/manpage.d/ipsec_sockaddrof.3.html deleted file mode 100644 index 3965ca62d..000000000 --- a/doc/manpage.d/ipsec_sockaddrof.3.html +++ /dev/null @@ -1,143 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PORTOF - -

IPSEC_PORTOF

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec portof - get port field of an ip_address -
- -ipsec setportof - set port field of an ip_address -
- -ipsec sockaddrof - get pointer to internal sockaddr of an ip_address -
- -ipsec sockaddrlenof - get length of internal sockaddr of an ip_address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int portof(const ip_address *src); - -
- -void setportof(int port, ip_address *dst); - -
- -struct sockaddr *sockaddrof(ip_address *src); - -
- -size_t sockaddrlenof(const ip_address *src); - -  -

DESCRIPTION

- -The -<freeswan.h> - -internal type -ip_address - -contains one of the -sockaddr - -types internally. -Reliance on this feature is discouraged, -but it may occasionally be necessary. -These functions provide low-level tools for this purpose. -

- -Portof - -and -setportof - -respectively read and write the port-number field of the internal -sockaddr. - -The values are in network byte order. -

- -Sockaddrof - -returns a pointer to the internal -sockaddr, - -for passing to other functions. -

- -Sockaddrlenof - -reports the size of the internal -sockaddr, - -for use in storage allocation. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

DIAGNOSTICS

- -Portof - -returns --1, - -sockaddrof - -returns -NULL, - -and -sockaddrlenof - -returns -0 - -if an unknown address family is found within the -ip_address. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -These functions all depend on low-level details of the -ip_address - -type, which are in principle subject to change. -Avoid using them unless really necessary. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_spi.5.html b/doc/manpage.d/ipsec_spi.5.html deleted file mode 100644 index b1cf89033..000000000 --- a/doc/manpage.d/ipsec_spi.5.html +++ /dev/null @@ -1,305 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SPI - -

IPSEC_SPI

-Section: File Formats (5)
Updated: 26 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_spi - list IPSEC Security Associations -  -

SYNOPSIS

- -ipsec - -spi - -

- -cat - -/proc/net/ipsec_spi - -

- -  -

DESCRIPTION

- -/proc/net/ipsec_spi - -is a read-only file that lists the current IPSEC Security Associations. -A Security Association (SA) is a transform through which packet contents -are to be processed before being forwarded. A transform can be an -IPv4-in-IPv4 or IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication -with no encryption), or an IPSEC Encapsulation Security Payload -(encryption, possibly including authentication). -

- -When a packet is passed from a higher networking layer through an IPSEC -virtual interface, a search in the extended routing table (see -ipsec_eroute(5)) - -yields -a IP protocol number -, -a Security Parameters Index (SPI) -and -an effective destination address -When an IPSEC packet arrives from the network, -its ostensible destination, an SPI and an IP protocol -specified by its outermost IPSEC header are used. -The destination/SPI/protocol combination is used to select a relevant SA. -(See -ipsec_spigrp(5) - -for discussion of how multiple transforms are combined.) -

- -An -spi , - -proto, - -daddr - -and -address_family - -arguments specify an SAID. -Proto - -is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol. -Spi - -is a number, preceded by '.' indicating hexadecimal and IPv4 or by ':' indicating hexadecimal and IPv6, -where each hexadecimal digit represents 4 bits, -between -0x100 - -and -0xffffffff; - -values from -0x0 - -to -0xff - -are reserved. -Daddr - -is a dotted-decimal IPv4 destination address or a coloned hex IPv6 destination address. -

- -An -SAID - -combines the three parameters above, such as: "tun.101@1.2.3.4" for IPv4 or "tun:101@3049:1::1" for IPv6 -

- -A table entry consists of: -

-
+
-SAID - -
+
-<transform name (proto,encalg,authalg)>: -
+
-direction (dir=) -
+
-source address (src=) -
+
-source and destination addresses and masks for inner header policy check -addresses (policy=), as dotted-quads or coloned hex, separated by '->', -for IPv4-in-IPv4 or IPv6-in-IPv6 SAs only -
+
-initialisation vector length and value (iv_bits=, iv=) if non-zero -
+
-out-of-order window size, number of out-of-order errors, sequence -number, recently received packet bitmask, maximum difference between -sequence numbers (ooowin=, ooo_errs=, seq=, bit=, max_seq_diff=) if SA -is AH or ESP and if individual items are non-zero -
+
-extra flags (flags=) if any are set -
+
-authenticator length in bits (alen=) if non-zero -
+
-authentication key length in bits (aklen=) if non-zero -
+
-authentication errors (auth_errs=) if non-zero -
+
-encryption key length in bits (eklen=) if non-zero -
+
-encryption size errors (encr_size_errs=) if non-zero -
+
-encryption padding error warnings (encr_pad_errs=) if non-zero -
+
-lifetimes legend, c=Current status, s=Soft limit when exceeded will -initiate rekeying, h=Hard limit will cause termination of SA (life(c,s,h)=) -
+
-number of connections to which the SA is allocated (c), that will cause a -rekey (s), that will cause an expiry (h) (alloc=), if any value is non-zero -
+
-number of bytes processesd by this SA (c), that will cause a rekey (s), that -will cause an expiry (h) (bytes=), if any value is non-zero -
+
-time since the SA was added (c), until rekey (s), until expiry (h), in seconds (add=) -
+
-time since the SA was first used (c), until rekey (s), until expiry (h), in seconds (used=), -if any value is non-zero -
+
-number of packets processesd by this SA (c), that will cause a rekey (s), that -will cause an expiry (h) (packets=), if any value is non-zero -
+
-time since the last packet was processed, in seconds (idle=), if SA has -been used -
-average compression ratio (ratio=) -
-  -

EXAMPLES

- -tun.12a@192.168.43.1 IPIP: dir=out src=192.168.43.2 - -
- - life(c,s,h)=bytes(14073,0,0)add(269,0,0) - -
- - use(149,0,0)packets(14,0,0) - -
- - idle=23 - -

- -is an outbound IPv4-in-IPv4 (protocol 4) tunnel-mode SA set up between machines -192.168.43.2 and 192.168.43.1 with an SPI of 12a in hexadecimal that has -passed about 14 kilobytes of traffic in 14 packets since it was created, -269 seconds ago, first used 149 seconds ago and has been idle for 23 -seconds. -

- -esp:9a35fc02@3049:1::1 ESP_3DES_HMAC_MD5: - -
- - dir=in src=9a35fc02@3049:1::2 - -
- - ooowin=32 seq=7149 bit=0xffffffff - -
- - alen=128 aklen=128 eklen=192 - -
- - life(c,s,h)=bytes(1222304,0,0)add(4593,0,0) - -
- - use(3858,0,0)packets(7149,0,0) - -
- - idle=23 - -

- -is an inbound Encapsulating Security Payload (protocol 50) SA on machine -3049:1::1 with an SPI of 9a35fc02 that uses 3DES as the encryption -cipher, HMAC MD5 as the authentication algorithm, an out-of-order -window of 32 packets, a present sequence number of 7149, every one of -the last 32 sequence numbers was received, the authenticator length and -keys is 128 bits, the encryption key is 192 bits (actually 168 for 3DES -since 1 of 8 bits is a parity bit), has passed 1.2 Mbytes of data in -7149 packets, was added 4593 seconds ago, first used -3858 seconds ago and has been idle for 23 seconds. -

- -  -

FILES

- -/proc/net/ipsec_spi, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(5), ipsec_eroute(5), -ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_spi(8), ipsec_version(5), -ipsec_pf_key(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. -  -

BUGS

- -The add and use times are awkward, displayed in seconds since machine -start. It would be better to display them in seconds before now for -human readability. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_spi.8.html b/doc/manpage.d/ipsec_spi.8.html deleted file mode 100644 index a40d06d9b..000000000 --- a/doc/manpage.d/ipsec_spi.8.html +++ /dev/null @@ -1,790 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SPI - -

IPSEC_SPI

-Section: Maintenance Commands (8)
Updated: 23 Oct 2001
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec spi - manage IPSEC Security Associations -  -

SYNOPSIS

- -
- -Note: In the following, -
- -<SA> - -means: ---af - -(inet | inet6) ---edst - -daddr ---spi - -spi ---proto - -proto OR ---said - -said, -
- -<life> - -means: ---life - -(soft | hard)-(allocations | bytes | addtime | usetime | packets)=value[,...] -

- -ipsec - -spi - -

- -ipsec - -spi - -<SA> - ---src - -src ---ah - -hmac-md5-96|hmac-sha1-96 - -[ ---replay_window - -replayw ] -[ -<life> - -] ---authkey - -akey -

- -ipsec - -spi - -<SA> - ---src - -src ---esp - -3des - -[ ---replay_window - -replayw ] -[ -<life> - -] ---enckey - -ekey -

- -ipsec - -spi - -<SA> - ---src - -src ---esp - -3des-md5-96|3des-sha1-96 - -[ ---replay_window - -replayw ] -[ -<life> - -] ---enckey - -ekey ---authkey - -akey -

- -ipsec - -spi - -<SA> - ---src - -src ---comp - -deflate - -

- -ipsec - -spi - -<SA> - ---ip4 - ---src - -encap-src ---dst - -encap-dst -

- -ipsec - -spi - -<SA> - ---ip6 - ---src - -encap-src ---dst - -encap-dst -

- -ipsec - -spi - -<SA> - ---del - -

- -ipsec - -spi - ---help - -

- -ipsec - -spi - ---version - -

- -ipsec - -spi - ---clear - -

- -  -

DESCRIPTION

- -Spi - -creates and deletes IPSEC Security Associations. -A Security Association (SA) is a transform through which packet -contents are to be processed before being forwarded. -A transform can be an IPv4-in-IPv4 or an IPv6-in-IPv6 encapsulation, -an IPSEC Authentication Header (authentication with no encryption), -or an IPSEC Encapsulation Security Payload (encryption, possibly -including authentication). -

- -When a packet is passed from a higher networking layer -through an IPSEC virtual interface, -a search in the extended routing table (see -ipsec_eroute(8)) - -yields an effective destination address, a -Security Parameters Index (SPI) and a IP protocol number. -When an IPSEC packet arrives from the network, -its ostensible destination, an SPI and an IP protocol -specified by its outermost IPSEC header are used. -The destination/SPI/protocol combination is used to select a relevant SA. -(See -ipsec_spigrp(8) - -for discussion of how multiple transforms are combined.) -

- -The -af, - -daddr, - -spi - -and -proto - -arguments specify the SA to be created or deleted. -af - -is the address family (inet for IPv4, inet6 for IPv6). -Daddr - -is a destination address -in dotted-decimal notation for IPv4 -or in a coloned hex notation for IPv6. -Spi - -is a number, preceded by '0x' for hexadecimal, -between -0x100 - -and -0xffffffff; - -values from -0x0 - -to -0xff - -are reserved. -Proto - -is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol. -The protocol must agree with the algorithm selected. -

- -Alternatively, the -said - -argument can also specify an SA to be created or deleted. -Said - -combines the three parameters above, such as: "tun.101@1.2.3.4" or "tun:101@1:2::3:4", -where the address family is specified by "." for IPv4 and ":" for IPv6. The address -family indicators substitute the "0x" for hexadecimal. -

- -The source address, -src, - -must also be provided for the inbound policy check to -function. The source address does not need to be included if inbound -policy checking has been disabled. -

- -Keys vectors must be entered as hexadecimal or base64 numbers. -They should be cryptographically strong random numbers. -

- -All hexadecimal numbers are entered as strings of hexadecimal digits -(0-9 and a-f), without spaces, preceded by '0x', where each hexadecimal -digit represents 4 bits. -All base64 numbers are entered as strings of base64 digits -
 (0-9, A-Z, a-z, '+' and '/'), without spaces, preceded by '0s', -where each hexadecimal digit represents 6 bits and '=' is used for padding. -

- -The deletion of an SA which has been grouped will result in the entire chain -being deleted. -

- -The form with no additional arguments lists the contents of -/proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed in -ipsec_spi(5). -

- -The lifetime severity of -soft - -sets a limit when the key management daemons are asked to rekey the SA. -The lifetime severity of -hard - -sets a limit when the SA must expire. -The lifetime type -allocations - -tells the system when to expire the SA because it is being shared by too many -eroutes (not currently used). The lifetime type of -bytes - -tells the system to expire the SA after a certain number of bytes have been -processed with that SA. The lifetime type of -addtime - -tells the system to expire the SA a certain number of seconds after the SA was -installed. The lifetime type of -usetime - -tells the system to expire the SA a certain number of seconds after that SA has -processed its first packet. The lifetime type of -packets - -tells the system to expire the SA after a certain number of packets have been -processed with that SA. -  -

OPTIONS

- -
-
--af - -
-specifies the address family (inet for IPv4, inet6 for IPv6) -
--edst - -
-specifies the effective destination -daddr - -of the Security Association -
--spi - -
-specifies the Security Parameters Index -spi - -of the Security Association -
--proto - -
-specifies the IP protocol -proto - -of the Security Association -
--said - -
-specifies the Security Association in monolithic format -
--ah - -
-add an SA for an IPSEC Authentication Header, -specified by the following transform identifier -(hmac-md5-96 - -or -hmac-sha1-96) - -(RFC2402, obsoletes RFC1826) -
hmac-md5-96 - -
-transform following the HMAC and MD5 standards, -using a 128-bit -key - -to produce a 96-bit authenticator (RFC2403) -
hmac-sha1-96 - -
-transform following the HMAC and SHA1 standards, -using a 160-bit -key - -to produce a 96-bit authenticator (RFC2404) -
--esp - -
-add an SA for an IPSEC Encapsulation Security Payload, -specified by the following -transform identifier (3des, - -or -3des-md5-96) - -(RFC2406, obsoletes RFC1827) -
3des - -
-encryption transform following the Triple-DES standard in -Cipher-Block-Chaining mode using a 64-bit -iv - -(internally generated) and a 192-bit 3DES -ekey - -(RFC2451) -
3des-md5-96 - -
-encryption transform following the Triple-DES standard in -Cipher-Block-Chaining mode with authentication provided by -HMAC and MD5 -(96-bit authenticator), -using a 64-bit -iv - -(internally generated), a 192-bit 3DES -ekey - -and a 128-bit HMAC-MD5 -akey - -(RFC2451, RFC2403) -
3des-sha1-96 - -
-encryption transform following the Triple-DES standard in -Cipher-Block-Chaining mode with authentication provided by -HMAC and SHA1 -(96-bit authenticator), -using a 64-bit -iv - -(internally generated), a 192-bit 3DES -ekey - -and a 160-bit HMAC-SHA1 -akey - -(RFC2451, RFC2404) -
--replay_window replayw - -
-sets the replay window size; valid values are decimal, 1 to 64 -
--life life_param[,life_param] - -
-sets the lifetime expiry; the format of -life_param - -consists of a comma-separated list of lifetime specifications without spaces; -a lifetime specification is comprised of a severity of -soft or hard - -followed by a '-', followed by a lifetime type of -allocations, bytes, addtime, usetime or packets - -followed by an '=' and finally by a value -
--comp - -
-add an SA for IPSEC IP Compression, -specified by the following -transform identifier (deflate) - -(RFC2393) -
deflate - -
-compression transform following the patent-free Deflate compression algorithm -(RFC2394) -
--ip4 - -
-add an SA for an IPv4-in-IPv4 -tunnel from -encap-src - -to -encap-dst - -
--ip6 - -
-add an SA for an IPv6-in-IPv6 -tunnel from -encap-src - -to -encap-dst - -
--src - -
-specify the source end of an IP-in-IP tunnel from -encap-src - -to -encap-dst - -and also specifies the source address of the Security Association to be -used in inbound policy checking and must be the same address -family as -af - -and -edst - -
--dst - -
-specify the destination end of an IP-in-IP tunnel from -encap-src - -to -encap-dst - -
--del - -
-delete the specified SA -
--clear - -
-clears the table of -SAs - -
--help - -
-display synopsis -
--version - -
-display version information -
-  -

EXAMPLES

- -To keep line lengths down and reduce clutter, -some of the long keys in these examples have been abbreviated -by replacing part of their text with -``...''. - -Keys used when the programs are actually run must, -of course, be the full length required for the particular algorithm. -

- -ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \ - -
- - --src gw1 \ - -
- - --esp 3des-md5-96 \ - -
- -   --enckey 0x6630...97ce \ - -
- - --authkey 0x9941...71df - -

- -sets up an SA from -gw1 - -to -gw2 - -with an SPI of -0x125 - -and protocol -ESP - -(50) using -3DES - -encryption with integral -MD5-96 - -authentication transform, using an encryption key of -0x6630...97ce - -and an authentication key of -0x9941...71df - -(see note above about abbreviated keys). -

- -ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah \ - -
- - --src 3049:9::9000:3101 \ - -
- - --ah hmac-md5-96 \ - -
- -   --authkey 0x1234...2eda \ - -

- -sets up an SA from -3049:9::9000:3101 - -to -3049:9::9000:3100 - -with an SPI of -0x150 - -and protocol -AH - -(50) using -MD5-96 - -authentication transform, using an authentication key of -0x1234...2eda - -(see note above about abbreviated keys). -

- -ipsec spi --said tun.987@192.168.100.100 --del - -

- -deletes an SA to -192.168.100.100 - -with an SPI of -0x987 - -and protocol -IPv4-in-IPv4 - -(4). -

- -ipsec spi --said tun:500@3049:9::1000:1 --del - -

- -deletes an SA to -3049:9::1000:1 - -with an SPI of -0x500 - -and protocol -IPv6-in-IPv6 - -(4). -

- -  -

FILES

- -/proc/net/ipsec_spi, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8), -ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. -  -

BUGS

- -The syntax is messy and the transform naming needs work. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
OPTIONS
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_spigrp.5.html b/doc/manpage.d/ipsec_spigrp.5.html deleted file mode 100644 index e0efcb73e..000000000 --- a/doc/manpage.d/ipsec_spigrp.5.html +++ /dev/null @@ -1,193 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SPIGRP - -

IPSEC_SPIGRP

-Section: File Formats (5)
Updated: 27 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_spigrp - list IPSEC Security Association groupings -  -

SYNOPSIS

- -ipsec - -spigrp - -

- -cat - -/proc/net/ipsec_spigrp - -

- -  -

DESCRIPTION

- -/proc/net/ipsec_spigrp - -is a read-only file that lists groups of IPSEC Security Associations -(SAs). -

- -An entry in the IPSEC extended routing table can only point (via an -SAID) to one SA. If more than one transform must be applied to a given -type of packet, this can be accomplished by setting up several SAs with -the same destination address but potentially different SPIs and -protocols, and grouping them with -ipsec_spigrp(8). - -

- -The SA groups are listed, one line per connection/group, as a sequence -of SAs to be applied (or that should have been applied, in the case of -an incoming packet) from inside to outside the packet. An SA is -identified by its SAID, which consists of protocol ("ah", "esp", "comp" or -"tun"), SPI (with '.' for IPv4 or ':' for IPv6 prefixed hexadecimal number ) and destination address -(IPv4 dotted quad or IPv6 coloned hex) prefixed by '@', in the format <proto><af><spi>@<dest>. -  -

EXAMPLES

- -
-
tun.3d0@192.168.2.110 - -
-comp.3d0@192.168.2.110 - -esp.187a101b@192.168.2.110 - -ah.187a101a@192.168.2.110 - -
-

- -is a group of 3 SAs, destined for -192.168.2.110 - -with an IPv4-in-IPv4 tunnel SA applied first with an SPI of -3d0 - -in hexadecimal, followed by a Deflate compression header to compress -the packet with CPI of -3d0 - -in hexadecimal, followed by an Encapsulating Security Payload header to -encrypt the packet with SPI -187a101b - -in hexadecimal, followed by an Authentication Header to authenticate the -packet with SPI -187a101a - -in hexadecimal, applied from inside to outside the packet. This could -be an incoming or outgoing group, depending on the address of the local -machine. -

- -

-
tun:3d0@3049:1::2 - -
-comp:3d0@3049:1::2 - -esp:187a101b@3049:1::2 - -ah:187a101a@3049:1::2 - -
-

- -is a group of 3 SAs, destined for -3049:1::2 - -with an IPv6-in-IPv6 tunnel SA applied first with an SPI of -3d0 - -in hexadecimal, followed by a Deflate compression header to compress -the packet with CPI of -3d0 - -in hexadecimal, followed by an Encapsulating Security Payload header to -encrypt the packet with SPI -187a101b - -in hexadecimal, followed by an Authentication Header to authenticate the -packet with SPI -187a101a - -in hexadecimal, applied from inside to outside the packet. This could -be an incoming or outgoing group, depending on the address of the local -machine. -

- -  -

FILES

- -/proc/net/ipsec_spigrp, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(5), ipsec_eroute(5), -ipsec_spi(5), ipsec_klipsdebug(5), ipsec_spigrp(8), ipsec_version(5), -ipsec_pf_key(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. -  -

BUGS

- -:-) - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_spigrp.8.html b/doc/manpage.d/ipsec_spigrp.8.html deleted file mode 100644 index 2e96c0574..000000000 --- a/doc/manpage.d/ipsec_spigrp.8.html +++ /dev/null @@ -1,280 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SPIGRP - -

IPSEC_SPIGRP

-Section: Maintenance Commands (8)
Updated: 21 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec spigrp - group/ungroup IPSEC Security Associations -  -

SYNOPSIS

- -ipsec - -spigrp - -

- -ipsec - -spigrp - -[ ---label - -label ] -af1 dst1 spi1 proto1 [ af2 dst2 spi2 proto2 [ af3 dst3 spi3 proto3 [ af4 dst4 spi4 proto4 ] ] ] -

- -ipsec - -spigrp - -[ ---label - -label ] ---said - -SA1 [ SA2 [ SA3 [ SA4 ] ] ] -

- -ipsec - -spigrp - ---help - -

- -ipsec - -spigrp - ---version - -

- -  -

DESCRIPTION

- -Spigrp - -groups IPSEC Security Associations (SAs) together or ungroups -previously grouped SAs. -An entry in the IPSEC extended -routing table can only point -(via a destination address, a Security Parameters Index (SPI) and -a protocol identifier) to one SA. -If more than one transform must be applied to a given type of packet, -this can be accomplished by setting up several SAs -with the same destination address but potentially different SPIs and protocols, -and grouping them with -spigrp. - -

- -The SAs to be grouped, -specified by destination address (DNS name lookup, IPv4 dotted quad or IPv6 coloned hex), SPI -('0x'-prefixed hexadecimal number) and protocol ("ah", "esp", "comp" or "tun"), -are listed from the inside transform to the -outside; -in other words, the transforms are applied in -the order of the command line and removed in the reverse -order. -The resulting SA group is referred to by its first SA (by -af1, - -dst1, - -spi1 - -and -proto1). - -

- -The --said option indicates that the SA IDs are to be specified as -one argument each, in the format <proto><af><spi>@<dest>. The SA IDs must -all be specified as separate parameters without the --said option or -all as monolithic parameters after the --said option. -

- -The SAs must already exist and must not already -be part of a group. -

- -If -spigrp - -is invoked with only one SA specification, -it ungroups the previously-grouped set of SAs containing -the SA specified. -

- -The --label option identifies all responses from that command -invocation with a user-supplied label, provided as an argument to the -label option. This can be helpful for debugging one invocation of the -command out of a large number. -

- -The command form with no additional arguments lists the contents of -/proc/net/ipsec_spigrp. The format of /proc/net/ipsec_spigrp is -discussed in ipsec_spigrp(5). -  -

EXAMPLES

- -
-
ipsec spigrp inet gw2 0x113 tun inet gw2 0x115 esp inet gw2 0x116 ah - -
-groups 3 SAs together, all destined for -gw2, - -but with an IPv4-in-IPv4 tunnel SA applied first with SPI -0x113, - -then an ESP header to encrypt the packet with SPI -0x115, - -and finally an AH header to authenticate the packet with SPI -0x116. - -
-

- -

-
ipsec spigrp --said tun.113@gw2 esp.115@gw2 ah.116@gw2 - -
-groups 3 SAs together, all destined for -gw2, - -but with an IPv4-in-IPv4 tunnel SA applied first with SPI -0x113, - -then an ESP header to encrypt the packet with SPI -0x115, - -and finally an AH header to authenticate the packet with SPI -0x116. - -
-

- -

-
ipsec spigrp --said tun:233@3049:1::1 esp:235@3049:1::1 ah:236@3049:1::1 - -
-groups 3 SAs together, all destined for -3049:1::1, - -but with an IPv6-in-IPv6 tunnel SA applied first with SPI -0x233, - -then an ESP header to encrypt the packet with SPI -0x235, - -and finally an AH header to authenticate the packet with SPI -0x236. - -
-

- -

-
ipsec spigrp inet6 3049:1::1 0x233 tun inet6 3049:1::1 0x235 esp inet6 3049:1::1 0x236 ah - -
-groups 3 SAs together, all destined for -3049:1::1, - -but with an IPv6-in-IPv6 tunnel SA applied first with SPI -0x233, - -then an ESP header to encrypt the packet with SPI -0x235, - -and finally an AH header to authenticate the packet with SPI -0x236. - -
-

- -  -

FILES

- -/proc/net/ipsec_spigrp, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_tncfg(8), ipsec_eroute(8), -ipsec_spi(8), ipsec_klipsdebug(8), ipsec_spigrp(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. -  -

BUGS

- -Yes, it really is limited to a maximum of four SAs, -although admittedly it's hard to see why you would need more. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_splitkeytoid.3.html b/doc/manpage.d/ipsec_splitkeytoid.3.html deleted file mode 100644 index 109cfafa7..000000000 --- a/doc/manpage.d/ipsec_splitkeytoid.3.html +++ /dev/null @@ -1,174 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_KEYBLOBTOID - -

IPSEC_KEYBLOBTOID

-Section: C Library Functions (3)
Updated: 25 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec keyblobtoid, splitkeytoid - generate key IDs from RSA keys -  -

SYNOPSIS

- -#include <freeswan.h> - -

-size_t keyblobtoid(const unsigned char *blob, - -
-  -size_t bloblen, char *dst, size_t dstlen); - -
- -size_t splitkeytoid(const unsigned char *e, size_t elen, - -
-  -const unsigned char *m, size_t mlen, char *dst, - -
-  -size_t dstlen); - -  -

DESCRIPTION

- -Keyblobtoid - -and -splitkeytoid - -generate -key IDs -from RSA keys, -for use in messages and reporting, -writing the result to -dst. - -A -key ID - -is a short ASCII string identifying a key; -currently it is just the first nine characters of the base64 -encoding of the RFC 2537/3110 ``byte blob'' representation of the key. -(Beware that no finite key ID can be collision-proof: -there is always some small chance of two random keys having the -same ID.) -

- -Keyblobtoid - -generates a key ID from a key which is already in the form of an -RFC 2537/3110 binary key -blob - -(encoded exponent length, exponent, modulus). -

- -Splitkeytoid - -generates a key ID from a key given in the form of a separate -(binary) exponent -e - -and modulus -m. - -

- -The -dstlen - -parameter of either -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant -KEYID_BUF - -which is the size of a buffer large enough for worst-case results. -

- -Both functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. - -With keys generated by -ipsec_rsasigkey(3), - -the first two base64 digits are always the same, -and the third carries only about one bit of information. -It's worse with keys using longer fixed exponents, -e.g. the 24-bit exponent that's common in X.509 certificates. -However, being able to relate key IDs to the full -base64 text form of keys by eye is sufficiently useful that this -waste of space seems justifiable. -The choice of nine digits is a compromise between bulk and -probability of collision. -  -

SEE ALSO

- -RFC 3110, -RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS), -Eastlake, 2001 -(superseding the older but better-known RFC 2537). -  -

DIAGNOSTICS

- -Fatal errors are: -key too short to supply enough bits to construct a complete key ID -(almost certainly indicating a garbage key); -exponent too long for its length to be representable. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_subnetinsubnet.3.html b/doc/manpage.d/ipsec_subnetinsubnet.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_subnetinsubnet.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_subnetishost.3.html b/doc/manpage.d/ipsec_subnetishost.3.html deleted file mode 100644 index 414a0d513..000000000 --- a/doc/manpage.d/ipsec_subnetishost.3.html +++ /dev/null @@ -1,274 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 28 Nov 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec sameaddr - are two addresses the same? -
- -ipsec addrcmp - ordered comparison of addresses -
- -ipsec samesubnet - are two subnets the same? -
- -ipsec addrinsubnet - is an address within a subnet? -
- -ipsec subnetinsubnet - is a subnet within another subnet? -
- -ipsec subnetishost - is a subnet a single host? -
- -ipsec samesaid - are two SA IDs the same? -
- -ipsec sameaddrtype - are two addresses of the same address family? -
- -ipsec samesubnettype - are two subnets of the same address family? -  -

SYNOPSIS

- -#include <freeswan.h> - -

-int sameaddr(const ip_address *a, const ip_address *b); - -
- -int addrcmp(const ip_address *a, const ip_address *b); - -
- -int samesubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int addrinsubnet(const ip_address *a, const ip_subnet *s); - -
- -int subnetinsubnet(const ip_subnet *a, const ip_subnet *b); - -
- -int subnetishost(const ip_subnet *s); - -
- -int samesaid(const ip_said *a, const ip_said *b); - -
- -int sameaddrtype(const ip_address *a, const ip_address *b); - -
- -int samesubnettype(const ip_subnet *a, const ip_subnet *b); - -  -

DESCRIPTION

- -These functions do various comparisons and tests on the -ip_address - -type and -ip_subnet - -types. -

- -Sameaddr - -returns -non-zero -if addresses -a - -and -b - -are identical, -and -0 - -otherwise. -Addresses of different families are never identical. -

- -Addrcmp - -returns --1, - -0, - -or -1 - -respectively -if address -a - -is less than, equal to, or greater than -b. - -If they are not of the same address family, -they are never equal; -the ordering reported in this case is arbitrary -(and probably not useful) but consistent. -

- -Samesubnet - -returns -non-zero -if subnets -a - -and -b - -are identical, -and -0 - -otherwise. -Subnets of different address families are never identical. -

- -Addrinsubnet - -returns -non-zero -if address -a - -is within subnet -s - -and -0 - -otherwise. -An address is never within a -subnet of a different address family. -

- -Subnetinsubnet - -returns -non-zero -if subnet -a - -is a subset of subnet -b - -and -0 - -otherwise. -A subnet is deemed to be a subset of itself. -A subnet is never a subset of another -subnet if their address families differ. -

- -Subnetishost - -returns -non-zero -if subnet -s - -is in fact only a single host, -and -0 - -otherwise. -

- -Samesaid - -returns -non-zero -if SA IDs -a - -and -b - -are identical, -and -0 - -otherwise. -

- -Sameaddrtype - -returns -non-zero -if addresses -a - -and -b - -are of the same address family, -and -0 - -otherwise. -

- -Samesubnettype - -returns -non-zero -if subnets -a - -and -b - -are of the same address family, -and -0 - -otherwise. -  -

SEE ALSO

- -inet(3), ipsec_initaddr(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_subnetof.3.html b/doc/manpage.d/ipsec_subnetof.3.html deleted file mode 100644 index a185d716b..000000000 --- a/doc/manpage.d/ipsec_subnetof.3.html +++ /dev/null @@ -1,107 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_SUBNETOF - -

IPSEC_SUBNETOF

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec subnetof - given Internet address and subnet mask, return subnet number -
- -ipsec hostof - given Internet address and subnet mask, return host part -
- -ipsec broadcastof - given Internet address and subnet mask, return broadcast address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-struct in_addr subnetof(struct in_addr addr, - -
-  -struct in_addr mask); - -
- -struct in_addr hostof(struct in_addr addr, - -
-  -struct in_addr mask); - -
- -struct in_addr broadcastof(struct in_addr addr, - -
-  -struct in_addr mask); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_networkof(3) - -for their replacements. -

- -Subnetof - -takes an Internet -address - -and a subnet -mask - -and returns the network part of the address -(all in network byte order). -Hostof - -similarly returns the host part, and -broadcastof - -returns the broadcast address (all-1s convention) for the network. -

- -These functions are provided to hide the Internet bit-munging inside -an API, in hopes of easing the eventual transition to IPv6. -  -

SEE ALSO

- -inet(3), ipsec_atosubnet(3) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Calling functions for this is more costly than doing it yourself. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_subnettoa.3.html b/doc/manpage.d/ipsec_subnettoa.3.html deleted file mode 100644 index 718fa935a..000000000 --- a/doc/manpage.d/ipsec_subnettoa.3.html +++ /dev/null @@ -1,448 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOADDR - -

IPSEC_ATOADDR

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII -
- -ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoaddr(const char *src, size_t srclen, - -
-  -struct in_addr *addr); - -
- -size_t addrtoa(struct in_addr addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *atosubnet(const char *src, size_t srclen, - -
-  -struct in_addr *addr, struct in_addr *mask); - -
- -size_t subnettoa(struct in_addr addr, struct in_addr mask, - -
-  -int format, char *dst, size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttoaddr(3) - -for their replacements. -

- -Atoaddr - -converts an ASCII name or dotted-decimal address into a binary address -(in network byte order). -Addrtoa - -does the reverse conversion, back to an ASCII dotted-decimal address. -Atosubnet - -and -subnettoa - -do likewise for the ``address/mask'' ASCII form used to write a -specification of a subnet. -

- -An address is specified in ASCII as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -ASCII-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of -addrtoa - -is always complete and does not contain leading zeros. -

- -The letters in -a hexadecimal address may be uppercase or lowercase or any mixture thereof. -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -Name lookup resorts to -getnetbyname(3) - -only if -gethostbyname(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -atoaddr. - -In addition, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0. - -

- -Atosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettoa - -generates the decimal-integer-bit-count -form of the mask, -with no leading zeros, -unless the mask is non-contiguous. -

- -The -srclen - -parameter of -atoaddr - -and -atosubnet - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -addrtoa - -and -subnettoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOA_BUF - -and -SUBNETTOA_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtoa - -and -subnettoa - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available. -This parameter is a hedge against future needs. -

- -The ASCII-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-ASCII functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoaddr - -are: -empty input; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal form; -dotted-decimal component too large to fit in 8 bits. -

- -Fatal errors in -atosubnet - -are: -no -/ - -in -src; - -atoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtoa - -and -subnettoa - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -The restriction of ASCII-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The ASCII-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_subnettot.3.html b/doc/manpage.d/ipsec_subnettot.3.html deleted file mode 100644 index 199937a35..000000000 --- a/doc/manpage.d/ipsec_subnettot.3.html +++ /dev/null @@ -1,569 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOADDR - -

IPSEC_TTOADDR

-Section: C Library Functions (3)
Updated: 28 Sept 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text -
- -ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -const char *tnatoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -size_t addrtot(const ip_address *addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *ttosubnet(const char *src, size_t srclen, - -
-  -int af, ip_subnet *dst); - -
- -size_t subnettot(const ip_subnet *sub, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttoaddr - -converts a text-string name or numeric address into a binary address -(in network byte order). -Tnatoaddr - -does the same conversion, -but the only text forms it accepts are -the ``official'' forms of -numeric address (dotted-decimal for IPv4, colon-hex for IPv6). -Addrtot - -does the reverse conversion, from binary address back to a text form. -Ttosubnet - -and -subnettot - -do likewise for the ``address/mask'' form used to write a -specification of a subnet. -

- -An IPv4 address is specified in text as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -text-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of applying -addrtot - -to an IPv4 address is always complete and does not contain leading zeros. -

- -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -An IPv6 address is specified in text with -colon-hex notation (e.g. -0:56:78ab:22:33:44:55:66), - -colon-hex with -:: - -abbreviating at most one subsequence of multiple zeros (e.g. -99:ab::54:068, - -which is synonymous with -99:ab:0:0:0:0:54:68), - -or a DNS name to be looked up via -gethostbyname(3). - -The result of applying -addrtot - -to an IPv6 address will use -:: - -abbreviation if possible, -and will not contain leading zeros. -

- -The letters in hexadecimal -may be uppercase or lowercase or any mixture thereof. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname2(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -IPv4 name lookup resorts to -getnetbyname(3) - -only if -gethostbyname2(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -ttoaddr. - -In addition, and preferably, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -in IPv4 means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0 - -or -::/0 - -in IPv4 or IPv6 respectively. -

- -Ttosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettot - -always generates the decimal-integer-bit-count -form of the mask, -with no leading zeros. -

- -The -srclen - -parameter of -ttoaddr - -and -ttosubnet - -specifies the length of the text string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -af - -parameter of -ttoaddr - -and -ttosubnet - -specifies the address family of interest. -It should be either -AF_INET - -or -AF_INET6. - -

- -The -dstlen - -parameter of -addrtot - -and -subnettot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOT_BUF - -and -SUBNETTOT_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtot - -and -subnettot - -specifies what format is to be used for the conversion. -The value -0 - -(not the character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available in -subnettot. - -Addrtot - -also accepts format values -'r' - -(signifying a text form suitable for DNS reverse lookups, -e.g. -4.3.2.1.IN-ADDR.ARPA. - -for IPv4 and -RFC 2874 format for IPv6), -and -'R' - -(signifying an alternate reverse-lookup form, -an error for IPv4 and RFC 1886 format for IPv6). -Reverse-lookup names always end with a ``.''. -

- -The text-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-text functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoaddr - -are: -empty input; -unknown address family; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal or colon-hex form; -dotted-decimal or colon-hex component too large. -

- -Fatal errors in -ttosubnet - -are: -no -/ - -in -src; - -ttoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtot - -and -subnettot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -Ttoaddr - -does not support the mixed colon-hex-dotted-decimal -convention used to embed an IPv4 address in an IPv6 address. -

- -Addrtot - -always uses the -:: - -abbreviation (which can appear only once in an address) for the -first - -sequence of multiple zeros in an IPv6 address. -One can construct addresses (unlikely ones) in which this is suboptimal. -

- -Addrtot - -'r' - -conversion of an IPv6 address uses lowercase hexadecimal, -not the uppercase used in RFC 2874's examples. -It takes careful reading of RFCs 2874, 2673, and 2234 to realize -that lowercase is technically legitimate here, -and there may be software which botches this -and hence would have trouble with lowercase hex. -

- -Possibly -subnettot - -ought to recognize the -%default - -case and generate that string as its output. -Currently it doesn't. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -Tnatoaddr - -probably should enforce completeness of dotted-decimal addresses. -

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_subnettypeof.3.html b/doc/manpage.d/ipsec_subnettypeof.3.html deleted file mode 100644 index ea0f83f82..000000000 --- a/doc/manpage.d/ipsec_subnettypeof.3.html +++ /dev/null @@ -1,238 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_INITSUBNET - -

IPSEC_INITSUBNET

-Section: C Library Functions (3)
Updated: 12 March 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec initsubnet - initialize an ip_subnet -
- -ipsec addrtosubnet - initialize a singleton ip_subnet -
- -ipsec subnettypeof - get address type of an ip_subnet -
- -ipsec masktocount - convert subnet mask to bit count -
- -ipsec networkof - get base address of an ip_subnet -
- -ipsec maskof - get subnet mask of an ip_subnet -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *initsubnet(const ip_address *addr, - -
-  -int maskbits, int clash, ip_subnet *dst); - -
- -const char *addrtosubnet(const ip_address *addr, - -
-  -ip_subnet *dst); - -

-int subnettypeof(const ip_subnet *src); - -
- -int masktocount(const ip_address *src); - -
- -void networkof(const ip_subnet *src, ip_address *dst); - -
- -void maskof(const ip_subnet *src, ip_address *dst); - -  -

DESCRIPTION

- -The -<freeswan.h> - -library uses an internal type -ip_subnet - -to contain a description of an IP subnet -(base address plus mask). -These functions provide basic tools for creating and examining this type. -

- -Initsubnet - -initializes a variable -*dst - -of type -ip_subnet - -from a base address and -a count of mask bits. -The -clash - -parameter specifies what to do if the base address includes -1 - -bits outside the prefix specified by the mask -(that is, in the ``host number'' part of the address): -

-
-
'0'
-zero out host-number bits -
'x'
-non-zero host-number bits are an error -
-
- -

- -Initsubnet - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -

- -Addrtosubnet - -initializes an -ip_subnet - -variable -*dst - -to a ``singleton subnet'' containing the single address -*addr. - -It returns -NULL - -for success and -a pointer to a string-literal error message for failure. -

- -Subnettypeof - -returns the address type of a subnet, -normally -AF_INET - -or -AF_INET6. - -(The -<freeswan.h> - -header file arranges to include the necessary headers for these -names to be known.) -

- -Masktocount - -converts a subnet mask, expressed as an address, to a bit count -suitable for use with -initsubnet. - -It returns --1 - -for error; see DIAGNOSTICS. -

- -Networkof - -fills in -*dst - -with the base address of subnet -src. - -

- -Maskof - -fills in -*dst - -with the subnet mask of subnet -src, - -expressed as an address. -  -

SEE ALSO

- -inet(3), ipsec_ttosubnet(3), ipsec_rangetosubnet(3) -  -

DIAGNOSTICS

- -Fatal errors in -initsubnet - -are: -unknown address family; -unknown -clash - -value; -impossible mask bit count; -non-zero host-number bits and -clash - -is -'x'. - -Fatal errors in -addrtosubnet - -are: -unknown address family. -Fatal errors in -masktocount - -are: -unknown address family; -mask bits not contiguous. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_tnatoaddr.3.html b/doc/manpage.d/ipsec_tnatoaddr.3.html deleted file mode 100644 index 199937a35..000000000 --- a/doc/manpage.d/ipsec_tnatoaddr.3.html +++ /dev/null @@ -1,569 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOADDR - -

IPSEC_TTOADDR

-Section: C Library Functions (3)
Updated: 28 Sept 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text -
- -ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -const char *tnatoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -size_t addrtot(const ip_address *addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *ttosubnet(const char *src, size_t srclen, - -
-  -int af, ip_subnet *dst); - -
- -size_t subnettot(const ip_subnet *sub, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttoaddr - -converts a text-string name or numeric address into a binary address -(in network byte order). -Tnatoaddr - -does the same conversion, -but the only text forms it accepts are -the ``official'' forms of -numeric address (dotted-decimal for IPv4, colon-hex for IPv6). -Addrtot - -does the reverse conversion, from binary address back to a text form. -Ttosubnet - -and -subnettot - -do likewise for the ``address/mask'' form used to write a -specification of a subnet. -

- -An IPv4 address is specified in text as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -text-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of applying -addrtot - -to an IPv4 address is always complete and does not contain leading zeros. -

- -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -An IPv6 address is specified in text with -colon-hex notation (e.g. -0:56:78ab:22:33:44:55:66), - -colon-hex with -:: - -abbreviating at most one subsequence of multiple zeros (e.g. -99:ab::54:068, - -which is synonymous with -99:ab:0:0:0:0:54:68), - -or a DNS name to be looked up via -gethostbyname(3). - -The result of applying -addrtot - -to an IPv6 address will use -:: - -abbreviation if possible, -and will not contain leading zeros. -

- -The letters in hexadecimal -may be uppercase or lowercase or any mixture thereof. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname2(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -IPv4 name lookup resorts to -getnetbyname(3) - -only if -gethostbyname2(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -ttoaddr. - -In addition, and preferably, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -in IPv4 means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0 - -or -::/0 - -in IPv4 or IPv6 respectively. -

- -Ttosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettot - -always generates the decimal-integer-bit-count -form of the mask, -with no leading zeros. -

- -The -srclen - -parameter of -ttoaddr - -and -ttosubnet - -specifies the length of the text string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -af - -parameter of -ttoaddr - -and -ttosubnet - -specifies the address family of interest. -It should be either -AF_INET - -or -AF_INET6. - -

- -The -dstlen - -parameter of -addrtot - -and -subnettot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOT_BUF - -and -SUBNETTOT_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtot - -and -subnettot - -specifies what format is to be used for the conversion. -The value -0 - -(not the character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available in -subnettot. - -Addrtot - -also accepts format values -'r' - -(signifying a text form suitable for DNS reverse lookups, -e.g. -4.3.2.1.IN-ADDR.ARPA. - -for IPv4 and -RFC 2874 format for IPv6), -and -'R' - -(signifying an alternate reverse-lookup form, -an error for IPv4 and RFC 1886 format for IPv6). -Reverse-lookup names always end with a ``.''. -

- -The text-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-text functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoaddr - -are: -empty input; -unknown address family; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal or colon-hex form; -dotted-decimal or colon-hex component too large. -

- -Fatal errors in -ttosubnet - -are: -no -/ - -in -src; - -ttoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtot - -and -subnettot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -Ttoaddr - -does not support the mixed colon-hex-dotted-decimal -convention used to embed an IPv4 address in an IPv6 address. -

- -Addrtot - -always uses the -:: - -abbreviation (which can appear only once in an address) for the -first - -sequence of multiple zeros in an IPv6 address. -One can construct addresses (unlikely ones) in which this is suboptimal. -

- -Addrtot - -'r' - -conversion of an IPv6 address uses lowercase hexadecimal, -not the uppercase used in RFC 2874's examples. -It takes careful reading of RFCs 2874, 2673, and 2234 to realize -that lowercase is technically legitimate here, -and there may be software which botches this -and hence would have trouble with lowercase hex. -

- -Possibly -subnettot - -ought to recognize the -%default - -case and generate that string as its output. -Currently it doesn't. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -Tnatoaddr - -probably should enforce completeness of dotted-decimal addresses. -

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_tncfg.5.html b/doc/manpage.d/ipsec_tncfg.5.html deleted file mode 100644 index e4082a28f..000000000 --- a/doc/manpage.d/ipsec_tncfg.5.html +++ /dev/null @@ -1,175 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TNCFG - -

IPSEC_TNCFG

-Section: File Formats (5)
Updated: 27 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_tncfg - lists IPSEC virtual interfaces attached to real interfaces -  -

SYNOPSIS

- -ipsec - -tncfg - -

- -cat - -/proc/net/ipsec_tncfg - -  -

DESCRIPTION

- -/proc/net/ipsec_tncfg - -is a read-only file which lists which IPSEC virtual interfaces are -attached to which real interfaces, through which packets will be -forwarded once processed by IPSEC. -

- -Each line lists one ipsec I/F. -A table entry consists of: -

-
+
-an ipsec virtual I/F name -
+
-a visual and machine parsable separator '->', separating the virtual I/F -and the physical I/F, -
+
-a physical I/F name, to which the ipsec virtual I/F is attached or NULL -if it is not attached, -
+
-the keyword -mtu=, - -
+
-the MTU of the ipsec virtual I/F, -
+
-the automatically adjusted effective MTU for PMTU discovery, in brackets, -
+
-a visual and machine parsable separator '->', separating the virtual I/F -MTU and the physical I/F MTU, -
+
-the MTU of the attached physical I/F. -.SHEXAMPLES - -
ipsec2 -> eth3 mtu=16260(1443) -> 1500 - -
-
-

- -shows that virtual device -ipsec2 - -with an MTU of -16260 - -is connected to physical device -eth3 - -with an MTU of -1500 - -and that the effective MTU as a result of PMTU discovery has been -automatically set to -1443. - -

-
ipsec0 -> wvlan0 mtu=1400(16260) -> 1500 - -
-
-

- -shows that virtual device -ipsec0 - -with an MTU of -1400 - -is connected to physical device -wvlan0 - -with an MTU of -1500 - -and no PMTU packets have gotten far enough to bump down the effective MTU -from its default of 16260. -

-
ipsec3 -> NULL mtu=0(0) -> 0 - -
-
-

- -shows that virtual device -ipsec3 - -is not connected to any physical device. -

- -  -

FILES

- -/proc/net/ipsec_tncfg, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_eroute(5), ipsec_spi(5), -ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_tncfg(8), ipsec_version(5), -ipsec_pf_key(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_tncfg.8.html b/doc/manpage.d/ipsec_tncfg.8.html deleted file mode 100644 index e5965267c..000000000 --- a/doc/manpage.d/ipsec_tncfg.8.html +++ /dev/null @@ -1,195 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TNCFG - -

IPSEC_TNCFG

-Section: Maintenance Commands (8)
Updated: 21 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec tncfg - associate IPSEC virtual interface with physical interface -  -

SYNOPSIS

- -ipsec - -tncfg - -

- -ipsec - -tncfg - ---attach - ---virtual - -virtual ---physical - -physical -

- -ipsec - -tncfg - ---detach - ---virtual - -virtual -

- -ipsec - -tncfg - ---clear - -

- -ipsec - -tncfg - ---version - -

- -ipsec - -tncfg - ---help - -  -

DESCRIPTION

- -Tncfg - -attaches/detaches IPSEC virtual interfaces to/from -physical interfaces, -through which packets will be forwarded once processed by IPSEC. -

- -The form with no additional arguments lists the contents of -/proc/net/ipsec_tncfg. The format of /proc/net/ipsec_tncfg is discussed -in ipsec_tncfg(5). -The ---attach - -form attaches the -virtual - -interface to the -physical - -one. -The ---detach - -form detaches the -virtual - -interface from whichever physical interface it is attached to. -The ---clear - -form clears all the -virtual - -interfaces from whichever physical interfaces they were attached to. -

- -Virtual interfaces typically have names like -ipsec0, - -while physical interfaces typically have names like -eth0 - -or -ppp0. - -  -

EXAMPLES

- -
-
ipsec tncfg --attach --virtual ipsec0 --physical eth0 - -
-attaches the -ipsec0 - -virtual device to the -eth0 - -physical device. -
-

- -  -

FILES

- -/proc/net/ipsec_tncfg, /usr/local/bin/ipsec -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_eroute(8), ipsec_spi(8), -ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_tncfg(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_trap_count.5.html b/doc/manpage.d/ipsec_trap_count.5.html deleted file mode 100644 index 8da655f77..000000000 --- a/doc/manpage.d/ipsec_trap_count.5.html +++ /dev/null @@ -1,74 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TRAP_COUNT - -

IPSEC_TRAP_COUNT

-Section: File Formats (5)
Updated: 19 Jun 2003
Index -Return to Main Contents
- - - - -  -

NAME

- -trap_count - KLIPS statistic on number of ACQUIREs -  -

SYNOPSIS

- -cat - -/proc/net/ipsec/stats/trap_count - -  -

DESCRIPTION

- -/proc/net/ipsec/stats/trap_count - -is a read-only file. It contains a hexadecimal number which records the -number of attempts to send PF_ACQUIRE messages. Only those recorded by -trap_sendcount were actually successfully passed to userland. Note that the -userland may still have lost them on its own. -

- -  -

FILES

- -/proc/net/ipsec/stats/trap_sendcount -  -

SEE ALSO

- -ipsec(8), ipsec_pf_key(5), trap_sendcount(5), pluto(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Michael C. Richardson <mcr@freeswan.org> - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_trap_sendcount.5.html b/doc/manpage.d/ipsec_trap_sendcount.5.html deleted file mode 100644 index 94f56b3a7..000000000 --- a/doc/manpage.d/ipsec_trap_sendcount.5.html +++ /dev/null @@ -1,72 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TRAP_SENDCOUNT - -

IPSEC_TRAP_SENDCOUNT

-Section: File Formats (5)
Updated: 19 Jun 2003
Index -Return to Main Contents
- - - - -  -

NAME

- -trap_sendcount - KLIPS statistic on number of successful ACQUIREs -  -

SYNOPSIS

- -cat - -/proc/net/ipsec/stats/trap_sendcount - -  -

DESCRIPTION

- -/proc/net/ipsec/stats/trap_sendcount - -is a read-only file. It contains a hexadecimal number which records the -number of successful PF_ACQUIRE messages that were sent. -

- -  -

FILES

- -/proc/net/ipsec/stats/trap_sendcount -  -

SEE ALSO

- -ipsec(8), ipsec_pf_key(5), trap_count(5), pluto(8) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Michael C. Richardson <mcr@freeswan.org> - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ttoaddr.3.html b/doc/manpage.d/ipsec_ttoaddr.3.html deleted file mode 100644 index 199937a35..000000000 --- a/doc/manpage.d/ipsec_ttoaddr.3.html +++ /dev/null @@ -1,569 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOADDR - -

IPSEC_TTOADDR

-Section: C Library Functions (3)
Updated: 28 Sept 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text -
- -ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -const char *tnatoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -size_t addrtot(const ip_address *addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *ttosubnet(const char *src, size_t srclen, - -
-  -int af, ip_subnet *dst); - -
- -size_t subnettot(const ip_subnet *sub, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttoaddr - -converts a text-string name or numeric address into a binary address -(in network byte order). -Tnatoaddr - -does the same conversion, -but the only text forms it accepts are -the ``official'' forms of -numeric address (dotted-decimal for IPv4, colon-hex for IPv6). -Addrtot - -does the reverse conversion, from binary address back to a text form. -Ttosubnet - -and -subnettot - -do likewise for the ``address/mask'' form used to write a -specification of a subnet. -

- -An IPv4 address is specified in text as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -text-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of applying -addrtot - -to an IPv4 address is always complete and does not contain leading zeros. -

- -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -An IPv6 address is specified in text with -colon-hex notation (e.g. -0:56:78ab:22:33:44:55:66), - -colon-hex with -:: - -abbreviating at most one subsequence of multiple zeros (e.g. -99:ab::54:068, - -which is synonymous with -99:ab:0:0:0:0:54:68), - -or a DNS name to be looked up via -gethostbyname(3). - -The result of applying -addrtot - -to an IPv6 address will use -:: - -abbreviation if possible, -and will not contain leading zeros. -

- -The letters in hexadecimal -may be uppercase or lowercase or any mixture thereof. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname2(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -IPv4 name lookup resorts to -getnetbyname(3) - -only if -gethostbyname2(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -ttoaddr. - -In addition, and preferably, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -in IPv4 means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0 - -or -::/0 - -in IPv4 or IPv6 respectively. -

- -Ttosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettot - -always generates the decimal-integer-bit-count -form of the mask, -with no leading zeros. -

- -The -srclen - -parameter of -ttoaddr - -and -ttosubnet - -specifies the length of the text string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -af - -parameter of -ttoaddr - -and -ttosubnet - -specifies the address family of interest. -It should be either -AF_INET - -or -AF_INET6. - -

- -The -dstlen - -parameter of -addrtot - -and -subnettot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOT_BUF - -and -SUBNETTOT_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtot - -and -subnettot - -specifies what format is to be used for the conversion. -The value -0 - -(not the character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available in -subnettot. - -Addrtot - -also accepts format values -'r' - -(signifying a text form suitable for DNS reverse lookups, -e.g. -4.3.2.1.IN-ADDR.ARPA. - -for IPv4 and -RFC 2874 format for IPv6), -and -'R' - -(signifying an alternate reverse-lookup form, -an error for IPv4 and RFC 1886 format for IPv6). -Reverse-lookup names always end with a ``.''. -

- -The text-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-text functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoaddr - -are: -empty input; -unknown address family; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal or colon-hex form; -dotted-decimal or colon-hex component too large. -

- -Fatal errors in -ttosubnet - -are: -no -/ - -in -src; - -ttoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtot - -and -subnettot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -Ttoaddr - -does not support the mixed colon-hex-dotted-decimal -convention used to embed an IPv4 address in an IPv6 address. -

- -Addrtot - -always uses the -:: - -abbreviation (which can appear only once in an address) for the -first - -sequence of multiple zeros in an IPv6 address. -One can construct addresses (unlikely ones) in which this is suboptimal. -

- -Addrtot - -'r' - -conversion of an IPv6 address uses lowercase hexadecimal, -not the uppercase used in RFC 2874's examples. -It takes careful reading of RFCs 2874, 2673, and 2234 to realize -that lowercase is technically legitimate here, -and there may be software which botches this -and hence would have trouble with lowercase hex. -

- -Possibly -subnettot - -ought to recognize the -%default - -case and generate that string as its output. -Currently it doesn't. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -Tnatoaddr - -probably should enforce completeness of dotted-decimal addresses. -

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ttodata.3.html b/doc/manpage.d/ipsec_ttodata.3.html deleted file mode 100644 index 960392fe0..000000000 --- a/doc/manpage.d/ipsec_ttodata.3.html +++ /dev/null @@ -1,439 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTODATA - -

IPSEC_TTODATA

-Section: C Library Functions (3)
Updated: 16 August 2003
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttodata, datatot - convert binary data bytes from and to text formats -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttodata(const char *src, size_t srclen, - -
-  -int base, char *dst, size_t dstlen, size_t *lenp); - -
- -const char *ttodatav(const char *src, size_t srclen, - -
-  -int base, char *dst, size_t dstlen, size_t *lenp, - -
-  -char *errp, size_t errlen, int flags); - -
- -size_t datatot(const char *src, size_t srclen, - -
-  -int format, char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttodata, - -ttodatav, - -and -datatot - -convert arbitrary binary data (e.g. encryption or authentication keys) -from and to more-or-less human-readable text formats. -

- -Currently supported formats are hexadecimal, base64, and characters. -

- -A hexadecimal text value begins with a -0x - -(or -0X) - -prefix and continues with two-digit groups -of hexadecimal digits (0-9, and a-f or A-F), -each group encoding the value of one binary byte, high-order digit first. -A single -_ - -(underscore) -between consecutive groups is ignored, permitting punctuation to improve -readability; doing this every eight digits seems about right. -

- -A base64 text value begins with a -0s - -(or -0S) - -prefix -and continues with four-digit groups of base64 digits (A-Z, a-z, 0-9, +, and /), -each group encoding the value of three binary bytes as described in -section 6.8 of RFC 2045. -If -flags - -has the -TTODATAV_IGNORESPACE - -bit on, blanks are ignore (after the prefix). -Note that the last one or two digits of a base64 group can be -= - -to indicate that fewer than three binary bytes are encoded. -

- -A character text value begins with a -0t - -(or -0T) - -prefix -and continues with text characters, each being the value of one binary byte. -

- -All these functions basically copy data from -src - -(whose size is specified by -srclen) - -to -dst - -(whose size is specified by -dstlen), - -doing the conversion en route. -If the result will not fit in -dst, - -it is truncated; -under no circumstances are more than -dstlen - -bytes of result written to -dst. - -Dstlen - -can be zero, in which case -dst - -need not be valid and no result bytes are written at all. -

- -The -base - -parameter of -ttodata - -and -ttodatav - -specifies what format the input is in; -normally it should be -0 - -to signify that this gets figured out from the prefix. -Values of -16, - -64, - -and -256 - -respectively signify hexadecimal, base64, and character-text formats -without prefixes. -

- -The -format - -parameter of -datatot, - -a single character used as a type code, -specifies which text format is wanted. -The value -0 - -(not ASCII -'0', - -but a zero value) specifies a reasonable default. -Other currently-supported values are: -

-
-
'x' - -
-continuous lower-case hexadecimal with a -0x - -prefix -
'h' - -
-lower-case hexadecimal with a -0x - -prefix and a -_ - -every eight digits -
':' - -
-lower-case hexadecimal with no prefix and a -: - -(colon) every two digits -
16 - -
-lower-case hexadecimal with no prefix or -_ - -
's' - -
-continuous base64 with a -0s - -prefix -
64 - -
-continuous base64 with no prefix -
-
- -

- -The default format is currently -'h'. - -

- -Ttodata - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -On success, -if and only if -lenp - -is non-NULL, -*lenp - -is set to the number of bytes required to contain the full untruncated result. -It is the caller's responsibility to check this against -dstlen - -to determine whether he has obtained a complete result. -The -*lenp - -value is correct even if -dstlen - -is zero, which offers a way to determine how much space would be needed -before having to allocate any. -

- -Ttodatav - -is just like -ttodata - -except that in certain cases, -if -errp - -is non-NULL, -the buffer pointed to by -errp - -(whose length is given by -errlen) - -is used to hold a more detailed error message. -The return value is NULL for success, -and is either -errp - -or a pointer to a string literal for failure. -If the size of the error-message buffer is -inadequate for the desired message, -ttodatav - -will fall back on returning a pointer to a literal string instead. -The -freeswan.h - -header file defines a constant -TTODATAV_BUF - -which is the size of a buffer large enough for worst-case results. -

- -The normal return value of -datatot - -is the number of bytes required -to contain the full untruncated result. -It is the caller's responsibility to check this against -dstlen - -to determine whether he has obtained a complete result. -The return value is correct even if -dstlen - -is zero, which offers a way to determine how much space would be needed -before having to allocate any. -A return value of -0 - -signals a fatal error of some kind -(see DIAGNOSTICS). -

- -A zero value for -srclen - -in -ttodata - -(but not -datatot!) - -is synonymous with -strlen(src). - -A non-zero -srclen - -in -ttodata - -must not include the terminating NUL. -

- -Unless -dstlen - -is zero, -the result supplied by -datatot - -is always NUL-terminated, -and its needed-size return value includes space for the terminating NUL. -

- -Several obsolete variants of these functions -(atodata, - -datatoa, - -atobytes, - -and -bytestoa) - -are temporarily also supported. -  -

SEE ALSO

- -sprintf(3), ipsec_atoaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttodata - -and -ttodatav - -are: -unknown characters in the input; -unknown or missing prefix; -unknown base; -incomplete digit group; -non-zero padding in a base64 less-than-three-bytes digit group; -zero-length input. -

- -Fatal errors in -datatot - -are: -unknown format code; -zero-length input. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Datatot - -should have a format code to produce character-text output. -

- -The -0s - -and -0t - -prefixes are the author's inventions and are not a standard -of any kind. -They have been chosen to avoid collisions with existing practice -(some C implementations use -0b - -for binary) -and possible confusion with unprefixed hexadecimal. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ttosa.3.html b/doc/manpage.d/ipsec_ttosa.3.html deleted file mode 100644 index 1e457fc24..000000000 --- a/doc/manpage.d/ipsec_ttosa.3.html +++ /dev/null @@ -1,453 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOSA - -

IPSEC_TTOSA

-Section: C Library Functions (3)
Updated: 26 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttosa, satot - convert IPsec Security Association IDs to and from text -
- -ipsec initsaid - initialize an SA ID -  -

SYNOPSIS

- -#include <freeswan.h> - -

-typedef struct { - -
-  -ip_address dst; - -
-  -ipsec_spi_t spi; - -
-  -int proto; - -
- -} ip_said; - -

-const char *ttosa(const char *src, size_t srclen, - -
-  -ip_said *sa); - -
- -size_t satot(const ip_said *sa, int format, - -
-  -char *dst, size_t dstlen); - -
- -void initsaid(const ip_address *addr, ipsec_spi_t spi, - -
-  -int proto, ip_said *dst); - -  -

DESCRIPTION

- -Ttosa - -converts an ASCII Security Association (SA) specifier into an -ip_said - -structure (containing -a destination-host address -in network byte order, -an SPI number in network byte order, and -a protocol code). -Satot - -does the reverse conversion, back to a text SA specifier. -Initsaid - -initializes an -ip_said - -from separate items of information. -

- -An SA is specified in text with a mail-like syntax, e.g. -esp.5a7@1.2.3.4. - -An SA specifier contains -a protocol prefix (currently -ah, - -esp, - -tun, - -comp, - -or -int), - -a single character indicating the address family -(. - -for IPv4, -: - -for IPv6), -an unsigned integer SPI number in hexadecimal (with no -0x - -prefix), -and an IP address. -The IP address can be any form accepted by -ipsec_ttoaddr(3), - -e.g. dotted-decimal IPv4 address, -colon-hex IPv6 address, -or DNS name. -

- -As a special case, the SA specifier -%passthrough4 - -or -%passthrough6 - -signifies the special SA used to indicate that packets should be -passed through unaltered. -(At present, these are synonyms for -tun.0@0.0.0.0 - -and -tun:0@:: - -respectively, -but that is subject to change without notice.) -%passthrough - -is a historical synonym for -%passthrough4. - -These forms are known to both -ttosa - -and -satot, - -so the internal representation is never visible. -

- -Similarly, the SA specifiers -%pass, - -%drop, - -%reject, - -%hold, - -%trap, - -and -%trapsubnet - -signify special ``magic'' SAs used to indicate that packets should be -passed, dropped, rejected (dropped with ICMP notification), -held, -and trapped (sent up to -ipsec_pluto(8), - -with either of two forms of -%hold - -automatically installed) -respectively. -These forms too are known to both routines, -so the internal representation of the magic SAs should never be visible. -

- -The -<freeswan.h> - -header file supplies the -ip_said - -structure, as well as a data type -ipsec_spi_t - -which is an unsigned 32-bit integer. -(There is no consistency between kernel and user on what such a type -is called, hence the header hides the differences.) -

- -The protocol code uses the same numbers that IP does. -For user convenience, given the difficulty in acquiring the exact set of -protocol names used by the kernel, -<freeswan.h> - -defines the names -SA_ESP, - -SA_AH, - -SA_IPIP, - -and -SA_COMP - -to have the same values as the kernel names -IPPROTO_ESP, - -IPPROTO_AH, - -IPPROTO_IPIP, - -and -IPPROTO_COMP. - -

- -<freeswan.h> - -also defines -SA_INT - -to have the value -61 - -(reserved by IANA for ``any host internal protocol'') -and -SPI_PASS, - -SPI_DROP, - -SPI_REJECT, - -SPI_HOLD, - -and -SPI_TRAP - -to have the values 256-260 (in host byte order) respectively. -These are used in constructing the magic SAs -(which always have address -0.0.0.0). - -

- -If -satot - -encounters an unknown protocol code, e.g. 77, -it yields output using a prefix -showing the code numerically, e.g. ``unk77''. -This form is -not - -recognized by -ttosa. - -

- -The -srclen - -parameter of -ttosa - -specifies the length of the string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -dstlen - -parameter of -satot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -<freeswan.h> - -header file defines a constant, -SATOT_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -satot - -specifies what format is to be used for the conversion. -The value -0 - -(not the ASCII character -'0', - -but a zero value) -specifies a reasonable default -(currently -lowercase protocol prefix, lowercase hexadecimal SPI, -dotted-decimal or colon-hex address). -The value -'f' - -is similar except that the SPI is padded with -0s - -to a fixed 32-bit width, to ease aligning displayed tables. -

- -Ttosa - -returns -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Satot - -returns -0 - -for a failure, and otherwise -always returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -

- -There is also, temporarily, support for some obsolete -forms of SA specifier which lack the address-family indicator. -  -

SEE ALSO

- -ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttosa - -are: -empty input; -input too small to be a legal SA specifier; -no -@ - -in input; -unknown protocol prefix; -conversion error in -ttoul - -or -ttoaddr. - -

- -Fatal errors in -satot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttosa( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ttosubnet.3.html b/doc/manpage.d/ipsec_ttosubnet.3.html deleted file mode 100644 index 199937a35..000000000 --- a/doc/manpage.d/ipsec_ttosubnet.3.html +++ /dev/null @@ -1,569 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOADDR - -

IPSEC_TTOADDR

-Section: C Library Functions (3)
Updated: 28 Sept 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text -
- -ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -const char *tnatoaddr(const char *src, size_t srclen, - -
-  -int af, ip_address *addr); - -
- -size_t addrtot(const ip_address *addr, int format, - -
-  -char *dst, size_t dstlen); - -

-const char *ttosubnet(const char *src, size_t srclen, - -
-  -int af, ip_subnet *dst); - -
- -size_t subnettot(const ip_subnet *sub, int format, - -
-  -char *dst, size_t dstlen); - -  -

DESCRIPTION

- -Ttoaddr - -converts a text-string name or numeric address into a binary address -(in network byte order). -Tnatoaddr - -does the same conversion, -but the only text forms it accepts are -the ``official'' forms of -numeric address (dotted-decimal for IPv4, colon-hex for IPv6). -Addrtot - -does the reverse conversion, from binary address back to a text form. -Ttosubnet - -and -subnettot - -do likewise for the ``address/mask'' form used to write a -specification of a subnet. -

- -An IPv4 address is specified in text as a -dotted-decimal address (e.g. -1.2.3.4), - -an eight-digit network-order hexadecimal number with the usual C prefix (e.g. -0x01020304, - -which is synonymous with -1.2.3.4), - -an eight-digit host-order hexadecimal number with a -0h - -prefix (e.g. -0h01020304, - -which is synonymous with -1.2.3.4 - -on a big-endian host and -4.3.2.1 - -on a little-endian host), -a DNS name to be looked up via -gethostbyname(3), - -or an old-style network name to be looked up via -getnetbyname(3). - -

- -A dotted-decimal address may be incomplete, in which case -text-to-binary conversion implicitly appends -as many instances of -.0 - -as necessary to bring it up to four components. -The components of a dotted-decimal address are always taken as -decimal, and leading zeros are ignored. -For example, -10 - -is synonymous with -10.0.0.0, - -and -128.009.000.032 - -is synonymous with -128.9.0.32 - -(the latter example is verbatim from RFC 1166). -The result of applying -addrtot - -to an IPv4 address is always complete and does not contain leading zeros. -

- -Use of hexadecimal addresses is -strongly - -discouraged; - -they are included only to save hassles when dealing with -the handful of perverted programs which already print -network addresses in hexadecimal. -

- -An IPv6 address is specified in text with -colon-hex notation (e.g. -0:56:78ab:22:33:44:55:66), - -colon-hex with -:: - -abbreviating at most one subsequence of multiple zeros (e.g. -99:ab::54:068, - -which is synonymous with -99:ab:0:0:0:0:54:68), - -or a DNS name to be looked up via -gethostbyname(3). - -The result of applying -addrtot - -to an IPv6 address will use -:: - -abbreviation if possible, -and will not contain leading zeros. -

- -The letters in hexadecimal -may be uppercase or lowercase or any mixture thereof. -

- -DNS names may be complete (optionally terminated with a ``.'') -or incomplete, and are looked up as specified by local system configuration -(see -resolver(5)). - -The -h_addr - -value returned by -gethostbyname2(3) - -is used, -so with current DNS implementations, -the result when the name corresponds to more than one address is -difficult to predict. -IPv4 name lookup resorts to -getnetbyname(3) - -only if -gethostbyname2(3) - -fails. -

- -A subnet specification is of the form network/mask. -The -network - -and -mask - -can be any form acceptable to -ttoaddr. - -In addition, and preferably, the -mask - -can be a decimal integer (leading zeros ignored) giving a bit count, -in which case -it stands for a mask with that number of high bits on and all others off -(e.g., -24 - -in IPv4 means -255.255.255.0). - -In any case, the mask must be contiguous -(a sequence of high bits on and all remaining low bits off). -As a special case, the subnet specification -%default - -is a synonym for -0.0.0.0/0 - -or -::/0 - -in IPv4 or IPv6 respectively. -

- -Ttosubnet - -ANDs the mask with the address before returning, -so that any non-network bits in the address are turned off -(e.g., -10.1.2.3/24 - -is synonymous with -10.1.2.0/24). - -Subnettot - -always generates the decimal-integer-bit-count -form of the mask, -with no leading zeros. -

- -The -srclen - -parameter of -ttoaddr - -and -ttosubnet - -specifies the length of the text string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -af - -parameter of -ttoaddr - -and -ttosubnet - -specifies the address family of interest. -It should be either -AF_INET - -or -AF_INET6. - -

- -The -dstlen - -parameter of -addrtot - -and -subnettot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines constants, -ADDRTOT_BUF - -and -SUBNETTOT_BUF, - -which are the sizes of buffers just large enough for worst-case results. -

- -The -format - -parameter of -addrtot - -and -subnettot - -specifies what format is to be used for the conversion. -The value -0 - -(not the character -'0', - -but a zero value) -specifies a reasonable default, -and is in fact the only format currently available in -subnettot. - -Addrtot - -also accepts format values -'r' - -(signifying a text form suitable for DNS reverse lookups, -e.g. -4.3.2.1.IN-ADDR.ARPA. - -for IPv4 and -RFC 2874 format for IPv6), -and -'R' - -(signifying an alternate reverse-lookup form, -an error for IPv4 and RFC 1886 format for IPv6). -Reverse-lookup names always end with a ``.''. -

- -The text-to-binary functions return NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -The binary-to-text functions return -0 - -for a failure, and otherwise -always return the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -inet(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoaddr - -are: -empty input; -unknown address family; -attempt to allocate temporary storage for a very long name failed; -name lookup failed; -syntax error in dotted-decimal or colon-hex form; -dotted-decimal or colon-hex component too large. -

- -Fatal errors in -ttosubnet - -are: -no -/ - -in -src; - -ttoaddr - -error in conversion of -network - -or -mask; - -bit-count mask too big; -mask non-contiguous. -

- -Fatal errors in -addrtot - -and -subnettot - -are: -unknown format. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -The interpretation of incomplete dotted-decimal addresses -(e.g. -10/24 - -means -10.0.0.0/24) - -differs from that of some older conversion -functions, e.g. those of -inet(3). - -The behavior of the older functions has never been -particularly consistent or particularly useful. -

- -Ignoring leading zeros in dotted-decimal components and bit counts -is arguably the most useful behavior in this application, -but it might occasionally cause confusion with the historical use of leading -zeros to denote octal numbers. -

- -Ttoaddr - -does not support the mixed colon-hex-dotted-decimal -convention used to embed an IPv4 address in an IPv6 address. -

- -Addrtot - -always uses the -:: - -abbreviation (which can appear only once in an address) for the -first - -sequence of multiple zeros in an IPv6 address. -One can construct addresses (unlikely ones) in which this is suboptimal. -

- -Addrtot - -'r' - -conversion of an IPv6 address uses lowercase hexadecimal, -not the uppercase used in RFC 2874's examples. -It takes careful reading of RFCs 2874, 2673, and 2234 to realize -that lowercase is technically legitimate here, -and there may be software which botches this -and hence would have trouble with lowercase hex. -

- -Possibly -subnettot - -ought to recognize the -%default - -case and generate that string as its output. -Currently it doesn't. -

- -It is barely possible that somebody, somewhere, -might have a legitimate use for non-contiguous subnet masks. -

- -Getnetbyname(3) - -is a historical dreg. -

- -Tnatoaddr - -probably should enforce completeness of dotted-decimal addresses. -

- -The restriction of text-to-binary error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The text-to-binary error-reporting convention lends itself -to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoaddr( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ttoul.3.html b/doc/manpage.d/ipsec_ttoul.3.html deleted file mode 100644 index b722dcc13..000000000 --- a/doc/manpage.d/ipsec_ttoul.3.html +++ /dev/null @@ -1,310 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOUL - -

IPSEC_TTOUL

-Section: C Library Functions (3)
Updated: 16 Aug 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoul, ultot - convert unsigned-long numbers to and from text -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoul(const char *src, size_t srclen, - -
-  -int base, unsigned long *n); - -
- -size_t ultot(unsigned long n, int format, char *dst, - -
-  -size_t dstlen); - -  -

DESCRIPTION

- -Ttoul - -converts a text-string number into a binary -unsigned long - -value. -Ultot - -does the reverse conversion, back to a text version. -

- -Numbers are specified in text as -decimal (e.g. -123), - -octal with a leading zero (e.g. -012, - -which has value 10), -or hexadecimal with a leading -0x - -(e.g. -0x1f, - -which has value 31) -in either upper or lower case. -

- -The -srclen - -parameter of -ttoul - -specifies the length of the string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -base - -parameter of -ttoul - -can be -8, - -10, - -or -16, - -in which case the number supplied is assumed to be of that form -(and in the case of -16, - -to lack any -0x - -prefix). -It can also be -0, - -in which case the number is examined for a leading zero -or a leading -0x - -to determine its base. -

- -The -dstlen - -parameter of -ultot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant, -ULTOT_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -ultot - -must be one of: -

-
-
'o'
-octal conversion with leading -0 - -
 8
-octal conversion with no leading -0 - -
'd'
-decimal conversion -
10
-same as -d - -
'x'
-hexadecimal conversion, including leading -0x - -
16
-hexadecimal conversion with no leading -0x - -
17
-like -16 - -except padded on left with -0s - -to eight digits (full width of a 32-bit number) -
-
- -

- -Ttoul - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Ultot - -returns -0 - -for a failure, and otherwise -returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL -(it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred). -  -

SEE ALSO

- -atol(3), strtoul(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoul - -are: -empty input; -unknown -base; - -non-digit character found; -number too large for an -unsigned long. - -

- -Fatal errors in -ultot - -are: -unknown -format. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Conversion of -0 - -with format -o - -yields -00. - -

- -Ultot - -format -17 - -is a bit of a kludge. -

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoul( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ultoa.3.html b/doc/manpage.d/ipsec_ultoa.3.html deleted file mode 100644 index 7669dce52..000000000 --- a/doc/manpage.d/ipsec_ultoa.3.html +++ /dev/null @@ -1,266 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ATOUL - -

IPSEC_ATOUL

-Section: C Library Functions (3)
Updated: 11 June 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec atoul, ultoa - convert unsigned-long numbers to and from ASCII -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *atoul(const char *src, size_t srclen, - -
-  -int base, unsigned long *n); - -
- -size_t ultoa(unsigned long n, int base, char *dst, - -
-  -size_t dstlen); - -  -

DESCRIPTION

- -These functions are obsolete; see -ipsec_ttoul(3) - -for their replacements. -

- -Atoul - -converts an ASCII number into a binary -unsigned long - -value. -Ultoa - -does the reverse conversion, back to an ASCII version. -

- -Numbers are specified in ASCII as -decimal (e.g. -123), - -octal with a leading zero (e.g. -012, - -which has value 10), -or hexadecimal with a leading -0x - -(e.g. -0x1f, - -which has value 31) -in either upper or lower case. -

- -The -srclen - -parameter of -atoul - -specifies the length of the ASCII string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -base - -parameter of -atoul - -can be -8, - -10, - -or -16, - -in which case the number supplied is assumed to be of that form -(and in the case of -16, - -to lack any -0x - -prefix). -It can also be -0, - -in which case the number is examined for a leading zero -or a leading -0x - -to determine its base, -or -13 - -(halfway between 10 and 16), -which has the same effect as -0 - -except that a non-hexadecimal -number is considered decimal regardless of any leading zero. -

- -The -dstlen - -parameter of -ultoa - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -

- -The -base - -parameter of -ultoa - -must be -8, - -10, - -or -16. - -

- -Atoul - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Ultoa - -returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL; -it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred. -  -

SEE ALSO

- -atol(3), strtoul(3) -  -

DIAGNOSTICS

- -Fatal errors in -atoul - -are: -empty input; -unknown -base; - -non-digit character found; -number too large for an -unsigned long. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -There is no provision for reporting an invalid -base - -parameter given to -ultoa. - -

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = atoul( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_ultot.3.html b/doc/manpage.d/ipsec_ultot.3.html deleted file mode 100644 index b722dcc13..000000000 --- a/doc/manpage.d/ipsec_ultot.3.html +++ /dev/null @@ -1,310 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_TTOUL - -

IPSEC_TTOUL

-Section: C Library Functions (3)
Updated: 16 Aug 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ttoul, ultot - convert unsigned-long numbers to and from text -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ttoul(const char *src, size_t srclen, - -
-  -int base, unsigned long *n); - -
- -size_t ultot(unsigned long n, int format, char *dst, - -
-  -size_t dstlen); - -  -

DESCRIPTION

- -Ttoul - -converts a text-string number into a binary -unsigned long - -value. -Ultot - -does the reverse conversion, back to a text version. -

- -Numbers are specified in text as -decimal (e.g. -123), - -octal with a leading zero (e.g. -012, - -which has value 10), -or hexadecimal with a leading -0x - -(e.g. -0x1f, - -which has value 31) -in either upper or lower case. -

- -The -srclen - -parameter of -ttoul - -specifies the length of the string pointed to by -src; - -it is an error for there to be anything else -(e.g., a terminating NUL) within that length. -As a convenience for cases where an entire NUL-terminated string is -to be converted, -a -srclen - -value of -0 - -is taken to mean -strlen(src). - -

- -The -base - -parameter of -ttoul - -can be -8, - -10, - -or -16, - -in which case the number supplied is assumed to be of that form -(and in the case of -16, - -to lack any -0x - -prefix). -It can also be -0, - -in which case the number is examined for a leading zero -or a leading -0x - -to determine its base. -

- -The -dstlen - -parameter of -ultot - -specifies the size of the -dst - -parameter; -under no circumstances are more than -dstlen - -bytes written to -dst. - -A result which will not fit is truncated. -Dstlen - -can be zero, in which case -dst - -need not be valid and no result is written, -but the return value is unaffected; -in all other cases, the (possibly truncated) result is NUL-terminated. -The -freeswan.h - -header file defines a constant, -ULTOT_BUF, - -which is the size of a buffer just large enough for worst-case results. -

- -The -format - -parameter of -ultot - -must be one of: -

-
-
'o'
-octal conversion with leading -0 - -
 8
-octal conversion with no leading -0 - -
'd'
-decimal conversion -
10
-same as -d - -
'x'
-hexadecimal conversion, including leading -0x - -
16
-hexadecimal conversion with no leading -0x - -
17
-like -16 - -except padded on left with -0s - -to eight digits (full width of a 32-bit number) -
-
- -

- -Ttoul - -returns NULL for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -Ultot - -returns -0 - -for a failure, and otherwise -returns the size of buffer which would -be needed to -accommodate the full conversion result, including terminating NUL -(it is the caller's responsibility to check this against the size of -the provided buffer to determine whether truncation has occurred). -  -

SEE ALSO

- -atol(3), strtoul(3) -  -

DIAGNOSTICS

- -Fatal errors in -ttoul - -are: -empty input; -unknown -base; - -non-digit character found; -number too large for an -unsigned long. - -

- -Fatal errors in -ultot - -are: -unknown -format. - -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -  -

BUGS

- -Conversion of -0 - -with format -o - -yields -00. - -

- -Ultot - -format -17 - -is a bit of a kludge. -

- -The restriction of error reports to literal strings -(so that callers don't need to worry about freeing them or copying them) -does limit the precision of error reporting. -

- -The error-reporting convention lends itself to slightly obscure code, -because many readers will not think of NULL as signifying success. -A good way to make it clearer is to write something like: -

- -

-
-const char *error;
-
-error = ttoul( /* ... */ );
-if (error != NULL) {
-        /* something went wrong */
-
- -
- -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_unspecaddr.3.html b/doc/manpage.d/ipsec_unspecaddr.3.html deleted file mode 100644 index 92f69d99c..000000000 --- a/doc/manpage.d/ipsec_unspecaddr.3.html +++ /dev/null @@ -1,166 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_ANYADDR - -

IPSEC_ANYADDR

-Section: C Library Functions (3)
Updated: 8 Sept 2000
Index -Return to Main Contents
- - -  -

NAME

- -ipsec anyaddr - get "any" address -
- -ipsec isanyaddr - test address for equality to "any" address -
- -ipsec unspecaddr - get "unspecified" address -
- -ipsec isunspecaddr - test address for equality to "unspecified" address -
- -ipsec loopbackaddr - get loopback address -
- -ipsec isloopbackaddr - test address for equality to loopback address -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *anyaddr(int af, ip_address *dst); - -
- -int isanyaddr(const ip_address *src); - -
- -const char *unspecaddr(int af, ip_address *dst); - -
- -int isunspecaddr(const ip_address *src); - -
- -const char *loopbackaddr(int af, ip_address *dst); - -
- -int isloopbackaddr(const ip_address *src); - -  -

DESCRIPTION

- -These functions fill in, and test for, special values of the -ip_address - -type. -

- -Anyaddr - -fills in the destination -*dst - -with the ``any'' address of address family -af - -(normally -AF_INET - -or -AF_INET6). - -The IPv4 ``any'' address is the one embodied in the old -INADDR_ANY - -macro. -

- -Isanyaddr - -returns -1 - -if the -src - -address equals the ``any'' address, -and -0 - -otherwise. -

- -Similarly, -unspecaddr - -supplies, and -isunspecaddr - -tests for, -the ``unspecified'' address, -which may be the same as the ``any'' address. -

- -Similarly, -loopbackaddr - -supplies, and -islookbackaddr - -tests for, -the loopback address. -

- -Anyaddr, - -unspecaddr, - -and -loopbackaddr - -return -NULL - -for success and -a pointer to a string-literal error message for failure; -see DIAGNOSTICS. -  -

SEE ALSO

- -inet(3), ipsec_addrtot(3), ipsec_sameaddr(3) -  -

DIAGNOSTICS

- -Fatal errors in the address-supplying functions are: -unknown address family. -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
DIAGNOSTICS
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_verify.8.html b/doc/manpage.d/ipsec_verify.8.html deleted file mode 100644 index 09d04894b..000000000 --- a/doc/manpage.d/ipsec_verify.8.html +++ /dev/null @@ -1,107 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_VERIFY - -

IPSEC_VERIFY

-Section: Maintenance Commands (8)
Updated: 8 June 2002
Index -Return to Main Contents
- - -  -

NAME

- -ipsec verify - see if FreeSWAN has been installed correctly -  -

SYNOPSIS

- -ipsec - -verify - -[ ---host - - name ] -  -

DESCRIPTION

- -

- -Invoked without argument, -verify - -examines the local system for a number of common system faults: -IPsec not in path, no secrets file generated, -pluto not running, and IPsec support not present in kernel -(or IPsec module not loaded). -If two or more interfaces are found, it performs checks relevant on an -IPsec gateway: whether IP forwarding is allowed, and if so, -whether MASQ or NAT rules are in play. -

- -In addition, -verify - -performs checks relevant to Opportunistic Encryption. -It looks in forward DNS for a TXT record for the system's hostname, and -in reverse DNS for a TXT record for the system's IP addresses. -It checks whether the system has a public IP. -

- -The ---host - -option causes -verify - -to look for a TXT record for -name - -in forward and reverse DNS. -  -

FILES

- -
-/proc/net/ipsec_eroute
-/etc/ipsec.secrets
-
- -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org> -by Michael Richardson. -  -

BUGS

- -Verify - -does not check for -ipchains - -masquerading. -

- -Verify - -does not look for TXT records for Opportunistic clients behind the system. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
FILES
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_version.3.html b/doc/manpage.d/ipsec_version.3.html deleted file mode 100644 index bcad75a46..000000000 --- a/doc/manpage.d/ipsec_version.3.html +++ /dev/null @@ -1,94 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_VERSION - -

IPSEC_VERSION

-Section: C Library Functions (3)
Updated: 21 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ipsec_version_code - get IPsec version code -
- -ipsec ipsec_version_string - get full IPsec version string -
- -ipsec ipsec_copyright_notice - get IPsec copyright notice -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ipsec_version_code(void); - -
- -const char *ipsec_version_string(void); - -
- -const char **ipsec_copyright_notice(void); - -  -

DESCRIPTION

- -These functions provide information on version numbering and copyright -of the Linux FreeS/WAN IPsec implementation. -

- -Ipsec_version_code - -returns a pointer to a string constant -containing the current IPsec version code, -such as ``1.92'' or ``snap2001Nov19b''. -

- -Ipsec_version_string - -returns a pointer to a string constant giving a full version identification, -consisting of the version code preceded by a prefix identifying the software, -e.g. ``Linux FreeS/WAN 1.92''. -

- -Ipsec_copyright_notice - -returns a pointer to a vector of pointers, -terminated by a -NULL, - -which is the text of a suitable copyright notice. -Each pointer points to a string constant (possibly empty) which is one line -of the somewhat-verbose copyright notice. -The strings are NUL-terminated and do not contain a newline; -supplying suitable line termination for the output device is -the caller's responsibility. -  -

SEE ALSO

- -ipsec(8) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_version.5.html b/doc/manpage.d/ipsec_version.5.html deleted file mode 100644 index 89bee0f97..000000000 --- a/doc/manpage.d/ipsec_version.5.html +++ /dev/null @@ -1,103 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_VERSION - -

IPSEC_VERSION

-Section: File Formats (5)
Updated: 29 Jun 2000
Index -Return to Main Contents
- - - - -  -

NAME

- -ipsec_version - lists KLIPS version information -  -

SYNOPSIS

- -cat - -/proc/net/ipsec_version - -  -

DESCRIPTION

- -/proc/net/ipsec_version - -is a read-only file which lists the currently running KLIPS version -information. -

- -  -

EXAMPLES

- -
-
FreeS/WAN version: 1.4 - -
-
-

- -shows that the currently loaded -KLIPS - -is from -FreeS/WAN 1.4. - -

- -  -

FILES

- -/proc/net/ipsec_version -  -

SEE ALSO

- -ipsec(8), ipsec_manual(8), ipsec_eroute(5), ipsec_spi(5), -ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_tncfg(8), ipsec_pf_key(5) -  -

HISTORY

- -Written for the Linux FreeS/WAN project -<http://www.freeswan.org/> -by Richard Guy Briggs. - - - - - - - - - - - - - - - - - - - -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
EXAMPLES
-
FILES
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_version_code.3.html b/doc/manpage.d/ipsec_version_code.3.html deleted file mode 100644 index bcad75a46..000000000 --- a/doc/manpage.d/ipsec_version_code.3.html +++ /dev/null @@ -1,94 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_VERSION - -

IPSEC_VERSION

-Section: C Library Functions (3)
Updated: 21 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ipsec_version_code - get IPsec version code -
- -ipsec ipsec_version_string - get full IPsec version string -
- -ipsec ipsec_copyright_notice - get IPsec copyright notice -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ipsec_version_code(void); - -
- -const char *ipsec_version_string(void); - -
- -const char **ipsec_copyright_notice(void); - -  -

DESCRIPTION

- -These functions provide information on version numbering and copyright -of the Linux FreeS/WAN IPsec implementation. -

- -Ipsec_version_code - -returns a pointer to a string constant -containing the current IPsec version code, -such as ``1.92'' or ``snap2001Nov19b''. -

- -Ipsec_version_string - -returns a pointer to a string constant giving a full version identification, -consisting of the version code preceded by a prefix identifying the software, -e.g. ``Linux FreeS/WAN 1.92''. -

- -Ipsec_copyright_notice - -returns a pointer to a vector of pointers, -terminated by a -NULL, - -which is the text of a suitable copyright notice. -Each pointer points to a string constant (possibly empty) which is one line -of the somewhat-verbose copyright notice. -The strings are NUL-terminated and do not contain a newline; -supplying suitable line termination for the output device is -the caller's responsibility. -  -

SEE ALSO

- -ipsec(8) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_version_string.3.html b/doc/manpage.d/ipsec_version_string.3.html deleted file mode 100644 index bcad75a46..000000000 --- a/doc/manpage.d/ipsec_version_string.3.html +++ /dev/null @@ -1,94 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_VERSION - -

IPSEC_VERSION

-Section: C Library Functions (3)
Updated: 21 Nov 2001
Index -Return to Main Contents
- - -  -

NAME

- -ipsec ipsec_version_code - get IPsec version code -
- -ipsec ipsec_version_string - get full IPsec version string -
- -ipsec ipsec_copyright_notice - get IPsec copyright notice -  -

SYNOPSIS

- -#include <freeswan.h> - -

-const char *ipsec_version_code(void); - -
- -const char *ipsec_version_string(void); - -
- -const char **ipsec_copyright_notice(void); - -  -

DESCRIPTION

- -These functions provide information on version numbering and copyright -of the Linux FreeS/WAN IPsec implementation. -

- -Ipsec_version_code - -returns a pointer to a string constant -containing the current IPsec version code, -such as ``1.92'' or ``snap2001Nov19b''. -

- -Ipsec_version_string - -returns a pointer to a string constant giving a full version identification, -consisting of the version code preceded by a prefix identifying the software, -e.g. ``Linux FreeS/WAN 1.92''. -

- -Ipsec_copyright_notice - -returns a pointer to a vector of pointers, -terminated by a -NULL, - -which is the text of a suitable copyright notice. -Each pointer points to a string constant (possibly empty) which is one line -of the somewhat-verbose copyright notice. -The strings are NUL-terminated and do not contain a newline; -supplying suitable line termination for the output device is -the caller's responsibility. -  -

SEE ALSO

- -ipsec(8) -  -

HISTORY

- -Written for the FreeS/WAN project by Henry Spencer. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
SEE ALSO
-
HISTORY
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/manpage.d/ipsec_whack.8.html b/doc/manpage.d/ipsec_whack.8.html deleted file mode 100644 index 2e2ce4c2f..000000000 --- a/doc/manpage.d/ipsec_whack.8.html +++ /dev/null @@ -1,1824 +0,0 @@ -Content-type: text/html - -Manpage of IPSEC_PLUTO - -

IPSEC_PLUTO

-Section: Maintenance Commands (8)
Updated: 28 March 1999
Index -Return to Main Contents
- -  -

NAME

- -ipsec pluto - IPsec IKE keying daemon -
- -ipsec whack - control interface for IPSEC keying daemon -  -

SYNOPSIS

- - - -
-
- -
ipsec pluto -[--help] -[--version] -[--optionsfrom filename] -[--nofork] -[--stderrlog] -[--noklips] -[--uniqueids] -[--interface interfacename] -[--ikeport portnumber] -[--ctlbase path] -[--secretsfile secrets-file] -[--adns pathname] -[--lwdnsq pathname] -[--perpeerlog] -[--perpeerlogbase dirname] -[--debug-none] -[--debug-all] -[--debug-raw] -[--debug-crypt] -[--debug-parsing] -[--debug-emitting] -[--debug-control] -[--debug-lifecycle] -[--debug-klips] -[--debug-dns] -[--debug-oppo] -[--debug-private] -
- -
ipsec whack -[--help] -[--version] -
- -
ipsec whack ---name connection-name -
- -[--id id] [--host ip-address] -[--ikeport port-number] -[--nexthop ip-address] -[--client subnet] -[--dnskeyondemand] -[--updown updown] -
- ---to -
- -[--id id] -[--host ip-address] -[--ikeport port-number] -[--nexthop ip-address] -[--client subnet] -[--dnskeyondemand] -[--updown updown] -
- -[--psk] -[--rsasig] -[--encrypt] -[--authenticate] -[--compress] -[--tunnel] -[--pfs] -[--disablearrivalcheck] -[--ipv4] -[--ipv6] -[--tunnelipv4] -[--tunnelipv6] -[--ikelifetime seconds] -[--ipseclifetime seconds] -[--rekeymargin seconds] -[--rekeyfuzz percentage] -[--keyingtries count] -[--dontrekey] -[--delete] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---keyid id -[--addkey] -[--pubkeyrsa key] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---myid id -
- -
ipsec whack ---listen|--unlisten -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---route|--unroute ---name connection-name -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---initiate|--terminate ---name connection-name -[--asynchronous] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack -[--tunnelipv4] -[--tunnelipv6] ---oppohere ip-address ---oppothere ip-address -
- -
ipsec whack ---delete ---name connection-name -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---deletestate state-number -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack -[--name connection-name] -[--debug-none] -[--debug-all] -[--debug-raw] -[--debug-crypt] -[--debug-parsing] -[--debug-emitting] -[--debug-control] -[--debug-lifecycle] -[--debug-klips] -[--debug-dns] -[--debug-oppo] -[--debug-private] -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---status -[--ctlbase path] -[--optionsfrom filename] -[--label string] -
- -
ipsec whack ---shutdown -[--ctlbase path] -[--optionsfrom filename] -[--label string] - - - -
-  -

DESCRIPTION

- -pluto - -is an IKE (``IPsec Key Exchange'') daemon. -whack - -is an auxiliary program to allow requests to be made to a running -pluto. - -

- -pluto - -is used to automatically build shared ``security associations'' on a -system that has IPsec, the secure IP protocol. -In other words, -pluto - -can eliminate much of the work of manual keying. -The actual -secure transmission of packets is the responsibility of other parts of -the system (see -KLIPS, - -the companion implementation of IPsec). -ipsec_auto(8) provides a more convenient interface to -pluto and whack. -  -

IKE's Job

- -

- -A Security Association (SA) is an agreement between two network nodes on -how to process certain traffic between them. This processing involves -encapsulation, authentication, encryption, or compression. -

- -IKE can be deployed on a network node to negotiate Security -Associations for that node. These IKE implementations can only -negotiate with other IKE implementations, so IKE must be on each node -that is to be an endpoint of an IKE-negotiated Security Association. -No other nodes need to be running IKE. -

- -An IKE instance (i.e. an IKE implementation on a particular network -node) communicates with another IKE instance using UDP IP packets, so -there must be a route between the nodes in each direction. -

- -The negotiation of Security Associations requires a number of choices -that involve tradeoffs between security, convenience, trust, and -efficiency. These are policy issues and are normally specified to the -IKE instance by the system administrator. -

- -IKE deals with two kinds of Security Associations. The first part of -a negotiation between IKE instances is to build an ISAKMP SA. An -ISAKMP SA is used to protect communication between the two IKEs. -IPsec SAs can then be built by the IKEs - these are used to carry -protected IP traffic between the systems. -

- -The negotiation of the ISAKMP SA is known as Phase 1. In theory, -Phase 1 can be accomplished by a couple of different exchange types, -but we only implement one called Main Mode (we don't implement -Aggressive Mode). -

- -Any negotiation under the protection of an ISAKMP SA, including the -negotiation of IPsec SAs, is part of Phase 2. The exchange type -that we use to negotiate an IPsec SA is called Quick Mode. -

- -IKE instances must be able to authenticate each other as part of their -negotiation of an ISAKMP SA. This can be done by several mechanisms -described in the draft standards. -

- -IKE negotiation can be initiated by any instance with any other. If -both can find an agreeable set of characteristics for a Security -Association, and both recognize each others authenticity, they can set -up a Security Association. The standards do not specify what causes -an IKE instance to initiate a negotiation. -

- -In summary, an IKE instance is prepared to automate the management of -Security Associations in an IPsec environment, but a number of issues -are considered policy and are left in the system administrator's hands. -  -

Pluto

- -

- -pluto is an implementation of IKE. It runs as a daemon on a network -node. Currently, this network node must be a LINUX system running the -KLIPS implementation of IPsec. -

- -pluto only implements a subset of IKE. This is enough for it to -interoperate with other instances of pluto, and many other IKE -implementations. We are working on implementing more of IKE. -

- -The policy for acceptable characteristics for Security Associations is -mostly hardwired into the code of pluto (spdb.c). Eventually -this will be moved into a security policy database with reasonable -expressive power and more convenience. -

- -pluto uses shared secrets or RSA signatures to authenticate -peers with whom it is negotiating. -

- -pluto initiates negotiation of a Security Association when it is -manually prodded: the program whack is run to trigger this. -It will also initiate a negotiation when KLIPS traps an outbound packet -for Opportunistic Encryption. -

- -pluto implements ISAKMP SAs itself. After it has negotiated the -characteristics of an IPsec SA, it directs KLIPS to implement it. -It also invokes a script to adjust any firewall and issue route(8) -commands to direct IP packets through KLIPS. -

- -When pluto shuts down, it closes all Security Associations. -  -

Before Running Pluto

- -

- -pluto runs as a daemon with userid root. Before running it, a few -things must be set up. -

- -pluto requires KLIPS, the FreeS/WAN implementation of IPsec. -All of the components of KLIPS and pluto should be installed. -

- -pluto supports multiple public networks (that is, networks -that are considered insecure and thus need to have their traffic -encrypted or authenticated). It discovers the -public interfaces to use by looking at all interfaces that are -configured (the --interface option can be used to limit -the interfaces considered). -It does this only when whack tells it to --listen, -so the interfaces must be configured by then. Each interface with a name of the form -ipsec[0-9] is taken as a KLIPS virtual public interface. -Another network interface with the same IP address (there should be only -one) is taken as the corresponding real public -interface. ifconfig(8) with the -a flag will show -the name and status of each network interface. -

- -pluto requires a database of preshared secrets and RSA private keys. -This is described in the -ipsec.secrets(5). - -pluto is told of RSA public keys via whack commands. -If the connection is Opportunistic, and no RSA public key is known, -pluto will attempt to fetch RSA keys using the Domain Name System. -  -

Setting up KLIPS for pluto

- -

- -The most basic network topology that pluto supports has two security -gateways negotiating on behalf of client subnets. The diagram of RGB's -testbed is a good example (see klips/doc/rgb_setup.txt). -

- -The file INSTALL in the base directory of this distribution -explains how to start setting up the whole system, including KLIPS. -

- -Make sure that the security gateways have routes to each other. This -is usually covered by the default route, but may require issuing -route(8) - -commands. The route must go through a particular IP -interface (we will assume it is eth0, but it need not be). The -interface that connects the security gateway to its client must be a -different one. -

- -It is necessary to issue a -ipsec_tncfg(8) - -command on each gateway. The required command is: -

-   ipsec tncfg --attach --virtual ipsec0 --physical eth0 -

-A command to set up the ipsec0 virtual interface will also need to be -run. It will have the same parameters as the command used to set up -the physical interface to which it has just been connected using -ipsec_tncfg(8). - -  -

ipsec.secrets file

- -

- -A pluto daemon and another IKE daemon (for example, another instance -of pluto) must convince each other that they are who they are supposed -to be before any negotiation can succeed. This authentication is -accomplished by using either secrets that have been shared beforehand -(manually) or by using RSA signatures. There are other techniques, -but they have not been implemented in pluto. -

- -The file /etc/ipsec.secrets is used to keep preshared secret keys -and RSA private keys for -authentication with other IKE daemons. For debugging, there is an -argument to the pluto command to use a different file. -This file is described in -ipsec.secrets(5). - -  -

Running Pluto

- -

- -To fire up the daemon, just type pluto (be sure to be running as -the superuser). -The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. -pluto must be run by the superuser to be able to use the UDP 500 port. -

- -pluto attempts to create a lockfile with the name -/var/run/pluto.pid. If the lockfile cannot be created, -pluto exits - this prevents multiple plutos from -competing Any ``leftover'' lockfile must be removed before -pluto will run. pluto writes its pid into this file so -that scripts can find it. This lock will not function properly if it -is on an NFS volume (but sharing locks on multiple machines doesn't -make sense anyway). -

- -pluto then forks and the parent exits. This is the conventional -``daemon fork''. It can make debugging awkward, so there is an option -to suppress this fork. -

- -All logging, including diagnostics, is sent to -syslog(3) - -with facility=authpriv; -it decides where to put these messages (possibly in /var/log/secure). -Since this too can make debugging awkward, there is an option to -steer logging to stderr. -

- -If the --perpeerlog option is given, then pluto will open -a log file per connection. By default, this is in /var/log/pluto/peer, -in a subdirectory formed by turning all dot (.) [IPv4} or colon (:) -[IPv6] into slashes (/). -

- -The base directory can be changed with the --perpeerlogbase. -

- -Once pluto is started, it waits for requests from whack. -  -

Pluto's Internal State

- -

- -To understand how to use pluto, it is helpful to understand a little -about its internal state. Furthermore, the terminology is needed to decipher -some of the diagnostic messages. -

- -The (potential) connection database describes attributes of a -connection. These include the IP addresses of the hosts and client -subnets and the security characteristics desired. pluto -requires this information (simply called a connection) before it can -respond to a request to build an SA. Each connection is given a name -when it is created, and all references are made using this name. -

- -During the IKE exchange to build an SA, the information about the -negotiation is represented in a state object. Each state object -reflects how far the negotiation has reached. Once the negotiation is -complete and the SA established, the state object remains to represent -the SA. When the SA is terminated, the state object is discarded. -Each State object is given a serial number and this is used to refer -to the state objects in logged messages. -

- -Each state object corresponds to a connection and can be thought of -as an instantiation of that connection. -At any particular time, there may be any number of state objects -corresponding to a particular connection. -Often there is one representing an ISAKMP SA and another representing -an IPsec SA. -

- -KLIPS hooks into the routing code in a LINUX kernel. -Traffic to be processed by an IPsec SA must be directed through -KLIPS by routing commands. Furthermore, the processing to be -done is specified by ipsec eroute(8) commands. -pluto takes the responsibility of managing both of these special -kinds of routes. -

- -Each connection may be routed, and must be while it has an IPsec SA. -The connection specifies the characteristics of the route: the -interface on this machine, the ``gateway'' (the nexthop), -and the peer's client subnet. Two -connections may not be simultaneously routed if they are for the same -peer's client subnet but use different interfaces or gateways -(pluto's logic does not reflect any advanced routing capabilities). -

- -Each eroute is associated with the state object for an IPsec SA -because it has the particular characteristics of the SA. -Two eroutes conflict if they specify the identical local -and remote clients (unlike for routes, the local clients are -taken into account). -

- -When pluto needs to install a route for a connection, -it must make sure that no conflicting route is in use. If another -connection has a conflicting route, that route will be taken down, as long -as there is no IPsec SA instantiating that connection. -If there is such an IPsec SA, the attempt to install a route will fail. -

- -There is an exception. If pluto, as Responder, needs to install -a route to a fixed client subnet for a connection, and there is -already a conflicting route, then the SAs using the route are deleted -to make room for the new SAs. The rationale is that the new -connection is probably more current. The need for this usually is a -product of Road Warrior connections (these are explained later; they -cannot be used to initiate). -

- -When pluto needs to install an eroute for an IPsec SA (for a -state object), first the state object's connection must be routed (if -this cannot be done, the eroute and SA will not be installed). -If a conflicting eroute is already in place for another connection, -the eroute and SA will not be installed (but note that the routing -exception mentioned above may have already deleted potentially conflicting SAs). -If another IPsec -SA for the same connection already has an eroute, all its outgoing traffic -is taken over by the new eroute. The incoming traffic will still be -processed. This characteristic is exploited during rekeying. -

- -All of these routing characteristics are expected change when -KLIPS is modified to use the firewall hooks in the LINUX 2.4.x -kernel. -  -

Using Whack

- -

- -whack is used to command a running pluto. -whack uses a UNIX domain socket to speak to pluto -(by default, /var/pluto.ctl). -

- -whack has an intricate argument syntax. -This syntax allows many different functions to be specified. -The help form shows the usage or version information. -The connection form gives pluto a description of a potential connection. -The public key form informs pluto of the RSA public key for a potential peer. -The delete form deletes a connection description and all SAs corresponding -to it. -The listen form tells pluto to start or stop listening on the public interfaces -for IKE requests from peers. -The route form tells pluto to set up routing for a connection; -the unroute form undoes this. -The initiate form tells pluto to negotiate an SA corresponding to a connection. -The terminate form tells pluto to remove all SAs corresponding to a connection, -including those being negotiated. -The status form displays the pluto's internal state. -The debug form tells pluto to change the selection of debugging output -``on the fly''. The shutdown form tells -pluto to shut down, deleting all SAs. -

- -Most options are specific to one of the forms, and will be described -with that form. There are three options that apply to all forms. -

-
--ctlbase path
-path.ctl is used as the UNIX domain socket for talking -to pluto. -This option facilitates debugging. -
--optionsfrom filename
-adds the contents of the file to the argument list. -
--label string
-adds the string to all error messages generated by whack. -
-

- -The help form of whack is self-explanatory. -

-
--help
-display the usage message. -
--version
-display the version of whack. -
-

- -The connection form describes a potential connection to pluto. -pluto needs to know what connections can and should be negotiated. -When pluto is the initiator, it needs to know what to propose. -When pluto is the responder, it needs to know enough to decide whether -is is willing to set up the proposed connection. -

- -The description of a potential connection can specify a large number -of details. Each connection has a unique name. This name will appear -in a updown shell command, so it should not contain punctuation -that would make the command ill-formed. -

-
--name connection-name
-
-

- -The topology of -a connection is symmetric, so to save space here is half a picture: -

-   client_subnet<-->host:ikeport<-->nexthop<--- -

-A similar trick is used in the flags. The same flag names are used for -both ends. Those before the --to flag describe the left side -and those afterwards describe the right side. When pluto attempts -to use the connection, it decides whether it is the left side or the right -side of the connection, based on the IP numbers of its interfaces. -

-
--id id
-the identity of the end. Currently, this can be an IP address (specified -as dotted quad or as a Fully Qualified Domain Name, which will be resolved -immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@'' -to signify that it should not be resolved), or as user@FQDN, or as the -magic value %myid. -Pluto only authenticates the identity, and does not use it for -addressing, so, for example, an IP address need not be the one to which -packets are to be sent. If the option is absent, the -identity defaults to the IP address specified by --host. -%myid allows the identity to be separately specified (by the pluto or whack option --myid -or by the ipsec.conf(5) config setup parameter myid). -Otherwise, pluto tries to guess what %myid should stand for: -the IP address of %defaultroute, if it is supported by a suitable TXT record in the reverse domain for that IP address, -or the system's hostname, if it is supported by a suitable TXT record in its forward domain. - -
--host ip-address
-
--host %any
-
--host %opportunistic
-the IP address of the end (generally the public interface). -If pluto is to act as a responder -for IKE negotiations initiated from unknown IP addresses (the -``Road Warrior'' case), the -IP address should be specified as %any (currently, -the obsolete notation 0.0.0.0 is also accepted for this). -If pluto is to opportunistically initiate the connection, -use %opportunistic -
--ikeport port-number
-the UDP port that IKE listens to on that host. The default is 500. -(pluto on this machine uses the port specified by its own command -line argument, so this only affects where pluto sends messages.) -
--nexthop ip-address
-where to route packets for the peer's client (presumably for the peer too, -but it will not be used for this). -When pluto installs an IPsec SA, it issues a route command. -It uses the nexthop as the gateway. -The default is the peer's IP address (this can be explicitly written as -%direct; the obsolete notation 0.0.0.0 is accepted). -This option is necessary if pluto's host's interface used for sending -packets to the peer is neither point-to-point nor directly connected to the -peer. -
--client subnet
-the subnet for which the IPsec traffic will be destined. If not specified, -the host will be the client. -The subnet can be specified in any of the forms supported by ipsec_atosubnet(3). -The general form is address/mask. The address can be either -a domain name or four decimal numbers (specifying octets) separated by dots. -The most convenient form of the mask is a decimal integer, specifying -the number of leading one bits in the mask. So, for example, 10.0.0.0/8 -would specify the class A network ``Net 10''. -
--dnskeyondemand]
-specifies that when an RSA public key is needed to authenticate this -host, and it isn't already known, fetch it from DNS. -
--updown updown
-specifies an external shell command to be run whenever pluto -brings up or down a connection. -The script is used to build a shell command, so it may contain positional -parameters, but ought not to have punctuation that would cause the -resulting command to be ill-formed. -The default is ipsec _updown. -
--to
-separates the specification of the left and right ends of the connection. -
-

- -The potential connection description also specifies characteristics of -rekeying and security. -

-
--psk
-Propose and allow preshared secret authentication for IKE peers. This authentication -requires that each side use the same secret. May be combined with --rsasig; -at least one must be specified. -
--rsasig
-Propose and allow RSA signatures for authentication of IKE peers. This authentication -requires that each side have have a private key of its own and know the -public key of its peer. May be combined with --psk; -at least one must be specified. -
--encrypt
-All proposed or accepted IPsec SAs will include non-null ESP. -The actual choices of transforms are wired into pluto. -
--authenticate
-All proposed IPsec SAs will include AH. -All accepted IPsec SAs will include AH or ESP with authentication. -The actual choices of transforms are wired into pluto. -Note that this has nothing to do with IKE authentication. -
--compress
-All proposed IPsec SAs will include IPCOMP (compression). -This will be ignored if KLIPS is not configured with IPCOMP support. -
--tunnel
-the IPsec SA should use tunneling. Implicit if the SA is for clients. -Must only be used with --authenticate or --encrypt. -
--ipv4
-The host addresses will be interpreted as IPv4 addresses. This is the -default. Note that for a connection, all host addresses must be of -the same Address Family (IPv4 and IPv6 use different Address Families). -
--ipv6
-The host addresses (including nexthop) will be interpreted as IPv6 addresses. -Note that for a connection, all host addresses must be of -the same Address Family (IPv4 and IPv6 use different Address Families). -
--tunnelipv4
-The client addresses will be interpreted as IPv4 addresses. The default is -to match what the host will be. This does not imply --tunnel so the -flag can be safely used when no tunnel is actually specified. -Note that for a connection, all tunnel addresses must be of the same -Address Family. -
--tunnelipv6
-The client addresses will be interpreted as IPv6 addresses. The default is -to match what the host will be. This does not imply --tunnel so the -flag can be safely used when no tunnel is actually specified. -Note that for a connection, all tunnel addresses must be of the same -Address Family. -
--pfs
-There should be Perfect Forward Secrecy - new keying material will -be generated for each IPsec SA rather than being derived from the ISAKMP -SA keying material. -Since the group to be used cannot be negotiated (a dubious feature of the -standard), pluto will propose the same group that was used during Phase 1. -We don't implement a stronger form of PFS which would require that the -ISAKMP SA be deleted after the IPSEC SA is negotiated. -
--disablearrivalcheck
-If the connection is a tunnel, allow packets arriving through the tunnel -to have any source and destination addresses. -
-

- -If none of the --encrypt, --authenticate, --compress, -or --pfs flags is given, the initiating the connection will -only build an ISAKMP SA. For such a connection, client subnets have -no meaning and must not be specified. -

- -More work is needed to allow for flexible policies. Currently -policy is hardwired in the source file spdb.c. The ISAKMP SAs may use -Oakley groups MODP1024 and MODP1536; 3DES encryption; SHA1-96 -and MD5-96 authentication. The IPsec SAs may use 3DES and -MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. -IPCOMP Compression is always Deflate. -

-
--ikelifetime seconds
-how long pluto will propose that an ISAKMP SA be allowed to live. -The default is 3600 (one hour) and the maximum is 28800 (8 hours). -This option will not affect what is accepted. -pluto will reject proposals that exceed the maximum. -
--ipseclifetime seconds
-how long pluto will propose that an IPsec SA be allowed to live. -The default is 28800 (eight hours) and the maximum is 86400 (one day). -This option will not affect what is accepted. -pluto will reject proposals that exceed the maximum. -
--rekeymargin seconds
-how long before an SA's expiration should pluto try to negotiate -a replacement SA. This will only happen if pluto was the initiator. -The default is 540 (nine minutes). -
--rekeyfuzz percentage
-maximum size of random component to add to rekeymargin, expressed as -a percentage of rekeymargin. pluto will select a delay uniformly -distributed within this range. By default, the percentage will be 100. -If greater determinism is desired, specify 0. It may be appropriate -for the percentage to be much larger than 100. -
--keyingtries count
-how many times pluto should try to negotiate an SA, -either for the first time or for rekeying. -A value of 0 is interpreted as a very large number: never give up. -The default is three. -
--dontrekey
-A misnomer. -Only rekey a connection if we were the Initiator and there was recent -traffic on the existing connection. -This applies to Phase 1 and Phase 2. -This is currently the only automatic way for a connection to terminate. -It may be useful with Road Warrior or Opportunistic connections. -
- -Since SA lifetime negotiation is take-it-or-leave it, a Responder -normally uses the shorter of the negotiated or the configured lifetime. -This only works because if the lifetime is shorter than negotiated, -the Responder will rekey in time so that everything works. -This interacts badly with --dontrekey. In this case, -the Responder will end up rekeying to rectify a shortfall in an IPsec SA -lifetime; for an ISAKMP SA, the Responder will accept the negotiated -lifetime. -
--delete
-when used in the connection form, it causes any previous connection -with this name to be deleted before this one is added. Unlike a -normal delete, no diagnostic is produced if there was no previous -connection to delete. Any routing in place for the connection is undone. -
-

- -The delete form deletes a named connection description and any -SAs established or negotiations initiated using this connection. -Any routing in place for the connection is undone. -

-
--delete
-
--name connection-name
-
-

- -The deletestate form deletes the state object with the specified serial number. -This is useful for selectively deleting instances of connections. -

-
--deletestate state-number
-
-

- -The route form of the whack command tells pluto to set up -routing for a connection. -Although like a traditional route, it uses an ipsec device as a -virtual interface. -Once routing is set up, no packets will be -sent ``in the clear'' to the peer's client specified in the connection. -A TRAP shunt eroute will be installed; if outbound traffic is caught, -Pluto will initiate the connection. -An explicit whack route is not always needed: if it hasn't been -done when an IPsec SA is being installed, one will be automatically attempted. -

- -When a routing is attempted for a connection, there must not already -be a routing for a different connection with the same subnet but different -interface or destination, or if -there is, it must not be being used by an IPsec SA. Otherwise the -attempt will fail. -

-
--route
-
--name connection-name
-
-

- -The unroute form of the whack command tells pluto to undo -a routing. pluto will refuse if an IPsec SA is using the connection. -If another connection is sharing the same routing, it will be left in place. -Without a routing, packets will be sent without encryption or authentication. -

-
--unroute
-
--name connection-name
-
-

- -The initiate form tells pluto to initiate a negotiation with another -pluto (or other IKE daemon) according to the named connection. -Initiation requires a route that --route would provide; -if none is in place at the time an IPsec SA is being installed, -pluto attempts to set one up. -

-
--initiate
-
--name connection-name
-
--asynchronous
-
-

- -The initiate form of the whack command will relay back from -pluto status information via the UNIX domain socket (unless ---asynchronous is specified). The status information is meant to -look a bit like that from FTP. Currently whack simply -copies this to stderr. When the request is finished (eg. the SAs are -established or pluto gives up), pluto closes the channel, -causing whack to terminate. -

- -The opportunistic initiate form is mainly used for debugging. -

-
--tunnelipv4
-
--tunnelipv6
-
--oppohere ip-address
-
--oppothere ip-address
-
-

- -This will cause pluto to attempt to opportunistically initiate a -connection from here to the there, even if a previous attempt -had been made. -The whack log will show the progress of this attempt. -

- -The terminate form tells pluto to delete any SAs that use the specified -connection and to stop any negotiations in process. -It does not prevent new negotiations from starting (the delete form -has this effect). -

-
--terminate
-
--name connection-name
-
-

- -The public key for informs pluto of the RSA public key for a potential peer. -Private keys must be kept secret, so they are kept in -ipsec.secrets(5). - -

-
--keyid id
-specififies the identity of the peer for which a public key should be used. -Its form is identical to the identity in the connection. -If no public key is specified, pluto attempts to find KEY records -from DNS for the id (if a FQDN) or through reverse lookup (if an IP address). -Note that there several interesting ways in which this is not secure. -
--addkey
-specifies that the new key is added to the collection; otherwise the -new key replaces any old ones. -
--pubkeyrsa key
-specifies the value of the RSA public key. It is a sequence of bytes -as described in RFC 2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''. -It is denoted in a way suitable for ipsec_ttodata(3). -For example, a base 64 numeral starts with 0s. -
-

- -The listen form tells pluto to start listening for IKE requests -on its public interfaces. To avoid race conditions, it is normal to -load the appropriate connections into pluto before allowing it -to listen. If pluto isn't listening, it is pointless to -initiate negotiations, so it will refuse requests to do so. Whenever -the listen form is used, pluto looks for public interfaces and -will notice when new ones have been added and when old ones have been -removed. This is also the trigger for pluto to read the -ipsec.secrets file. So listen may useful more than once. -

-
--listen
-start listening for IKE traffic on public interfaces. -
--unlisten
-stop listening for IKE traffic on public interfaces. -
-

- -The status form will display information about the internal state of -pluto: information about each potential connection, about -each state object, and about each shunt that pluto is managing -without an associated connection. -

-
--status
-
-

- -The shutdown form is the proper way to shut down pluto. -It will tear down the SAs on this machine that pluto has negotiated. -It does not inform its peers, so the SAs on their machines remain. -

-
--shutdown
-
-  -

Examples

- -

- -It would be normal to start pluto in one of the system initialization -scripts. It needs to be run by the superuser. Generally, no arguments are needed. -To run in manually, the superuser can simply type -

-   ipsec pluto -

-The command will immediately return, but a pluto process will be left -running, waiting for requests from whack or a peer. -

- -Using whack, several potential connections would be described: -

-
- -   ipsec whack --name silly ---host 127.0.0.1 --to --host 127.0.0.2 ---ikelifetime 900 --ipseclifetime 800 --keyingtries 3 - -
-

- -

Since this silly connection description specifies neither encryption, -authentication, nor tunneling, it could only be used to establish -an ISAKMP SA. -
-
- -   ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 ---to --host 10.0.0.2 --client 10.0.2.0/24 ---encrypt - -
-

- -

This is something that must be done on both sides. If the other -side is pluto, the same whack command could be used on it -(the command syntax is designed to not distinguish which end is ours). -

- -Now that the connections are specified, pluto is ready to handle -requests and replies via the public interfaces. We must tell it to discover -those interfaces and start accepting messages from peers: -

-   ipsec whack --listen -

- -If we don't immediately wish to bring up a secure connection between -the two clients, we might wish to prevent insecure traffic. -The routing form asks pluto to cause the packets sent from -our client to the peer's client to be routed through the ipsec0 -device; if there is no SA, they will be discarded: -

-   ipsec whack --route secret -

- -Finally, we are ready to get pluto to initiate negotiation -for an IPsec SA (and implicitly, an ISAKMP SA): -

-   ipsec whack --initiate --name secret -

-A small log of interesting events will appear on standard output -(other logging is sent to syslog). -

- -whack can also be used to terminate pluto cleanly, tearing down -all SAs that it has negotiated. -

-   ipsec whack --shutdown -

-Notification of any IPSEC SA deletion, but not ISAKMP SA deletion -is sent to the peer. Unfortunately, such Notification is not reliable. -Furthermore, pluto itself ignores Notifications. -  -

The updown command

- -

- -Whenever pluto brings a connection up or down, it invokes -the updown command. This command is specified using the --updown -option. This allows for customized control over routing and firewall manipulation. -

- -The updown is invoked for five different operations. Each of -these operations can be for our client subnet or for our host itself. -

-
prepare-host or prepare-client
-is run before bringing up a new connection if no other connection -with the same clients is up. Generally, this is useful for deleting a -route that might have been set up before pluto was run or -perhaps by some agent not known to pluto. -
route-host or route-client
-is run when bringing up a connection for a new peer client subnet -(even if prepare-host or prepare-client was run). The -command should install a suitable route. Routing decisions are based -only on the destination (peer's client) subnet address, unlike eroutes -which discriminate based on source too. -
unroute-host or unroute-client
-is run when bringing down the last connection for a particular peer -client subnet. It should undo what the route-host or route-client -did. -
up-host or up-client
-is run when bringing up a tunnel eroute with a pair of client subnets -that does not already have a tunnel eroute. -This command should install firewall rules as appropriate. -It is generally a good idea to allow IKE messages (UDP port 500) -travel between the hosts. -
down-host or down-client
-is run when bringing down the eroute for a pair of client subnets. -This command should delete firewall rules as appropriate. Note that -there may remain some inbound IPsec SAs with these client subnets. -
-

- -The script is passed a large number of environment variables to specify -what needs to be done. -

-
PLUTO_VERSION
-indicates what version of this interface is being used. This document -describes version 1.1. This is upwardly compatible with version 1.0. -
PLUTO_VERB
-specifies the name of the operation to be performed -(prepare-host,r prepare-client, -up-host, up-client, -down-host, or down-client). If the address family for -security gateway to security gateway communications is IPv6, then -a suffix of -v6 is added to the verb. -
PLUTO_CONNECTION
-is the name of the connection for which we are routing. -
PLUTO_NEXT_HOP
-is the next hop to which packets bound for the peer must be sent. -
PLUTO_INTERFACE
-is the name of the ipsec interface to be used. -
PLUTO_ME
-is the IP address of our host. -
PLUTO_MY_CLIENT
-is the IP address / count of our client subnet. -If the client is just the host, this will be the host's own IP address / max -(where max is 32 for IPv4 and 128 for IPv6). -
PLUTO_MY_CLIENT_NET
-is the IP address of our client net. -If the client is just the host, this will be the host's own IP address. -
PLUTO_MY_CLIENT_MASK
-is the mask for our client net. -If the client is just the host, this will be 255.255.255.255. -
PLUTO_PEER
-is the IP address of our peer. -
PLUTO_PEER_CLIENT
-is the IP address / count of the peer's client subnet. -If the client is just the peer, this will be the peer's own IP address / max -(where max is 32 for IPv4 and 128 for IPv6). -
PLUTO_PEER_CLIENT_NET
-is the IP address of the peer's client net. -If the client is just the peer, this will be the peer's own IP address. -
PLUTO_PEER_CLIENT_MASK
-is the mask for the peer's client net. -If the client is just the peer, this will be 255.255.255.255. -
-

- -All output sent by the script to stderr or stdout is logged. The -script should return an exit status of 0 if and only if it succeeds. -

- -Pluto waits for the script to finish and will not do any other -processing while it is waiting. -The script may assume that pluto will not change anything -while the script runs. -The script should avoid doing anything that takes much time and it -should not issue any command that requires processing by pluto. -Either of these activities could be performed by a background -subprocess of the script. -  -

Rekeying

- -

- -When an SA that was initiated by pluto has only a bit of -lifetime left, -pluto will initiate the creation of a new SA. This applies to -ISAKMP and IPsec SAs. -The rekeying will be initiated when the SA's remaining lifetime is -less than the rekeymargin plus a random percentage, between 0 and -rekeyfuzz, of the rekeymargin. -

- -Similarly, when an SA that was initiated by the peer has only a bit of -lifetime left, pluto will try to initiate the creation of a -replacement. -To give preference to the initiator, this rekeying will only be initiated -when the SA's remaining lifetime is half of rekeymargin. -If rekeying is done by the responder, the roles will be reversed: the -responder for the old SA will be the initiator for the replacement. -The former initiator might also initiate rekeying, so there may -be redundant SAs created. -To avoid these complications, make sure that rekeymargin is generous. -

- -One risk of having the former responder initiate is that perhaps -none of its proposals is acceptable to the former initiator -(they have not been used in a successful negotiation). -To reduce the chances of this happening, and to prevent loss of security, -the policy settings are taken from the old SA (this is the case even if -the former initiator is initiating). -These may be stricter than those of the connection. -

- -pluto will not rekey an SA if that SA is not the most recent of its -type (IPsec or ISAKMP) for its potential connection. -This avoids creating redundant SAs. -

- -The random component in the rekeying time (rekeyfuzz) is intended to -make certain pathological patterns of rekeying unstable. If both -sides decide to rekey at the same time, twice as many SAs as necessary -are created. This could become a stable pattern without the -randomness. -

- -Another more important case occurs when a security gateway has SAs -with many other security gateways. Each of these connections might -need to be rekeyed at the same time. This would cause a high peek -requirement for resources (network bandwidth, CPU time, entropy for -random numbers). The rekeyfuzz can be used to stagger the rekeying -times. -

- -Once a new set of SAs has been negotiated, pluto will never send -traffic on a superseded one. Traffic will be accepted on an old SA -until it expires. -  -

Selecting a Connection When Responding: Road Warrior Support

- -

- -When pluto receives an initial Main Mode message, it needs to -decide which connection this message is for. It picks based solely on -the source and destination IP addresses of the message. There might -be several connections with suitable IP addresses, in which case one -of them is arbitrarily chosen. (The ISAKMP SA proposal contained in -the message could be taken into account, but it is not.) -

- -The ISAKMP SA is negotiated before the parties pass further -identifying information, so all ISAKMP SA characteristics specified in -the connection description should be the same for every connection -with the same two host IP addresses. At the moment, the only -characteristic that might differ is authentication method. -

- -Up to this point, -all configuring has presumed that the IP addresses -are known to all parties ahead of time. This will not work -when either end is mobile (or assigned a dynamic IP address for other -reasons). We call this situation ``Road Warrior''. It is fairly tricky -and has some important limitations, most of which are features of -the IKE protocol. -

- -Only the initiator may be mobile: -the initiator may have an IP number unknown to the responder. When -the responder doesn't recognize the IP address on the first Main Mode -packet, it looks for a connection with itself as one end and %any -as the other. -If it cannot find one, it refuses to negotiate. If it -does find one, it creates a temporary connection that is a duplicate -except with the %any replaced by the source IP address from the -packet; if there was no identity specified for the peer, the new IP -address will be used. -

- -When pluto is using one of these temporary connections and -needs to find the preshared secret or RSA private key in ipsec.secrets, -and and the connection specified no identity for the peer, %any -is used as its identity. After all, the real IP address was apparently -unknown to the configuration, so it is unreasonable to require that -it be used in this table. -

- -Part way into the Phase 1 (Main Mode) negotiation using one of these -temporary connection descriptions, pluto will be receive an -Identity Payload. At this point, pluto checks for a more -appropriate connection, one with an identity for the peer that matches -the payload but which would use the same keys so-far used for -authentication. If it finds one, it will switch to using this better -connection (or a temporary derived from this, if it has %any -for the peer's IP address). It may even turn out that no connection -matches the newly discovered identity, including the current connection; -if so, pluto terminates negotiation. -

- -Unfortunately, if preshared secret authentication is being used, the -Identity Payload is encrypted using this secret, so the secret must be -selected by the responder without knowing this payload. This -limits there to being at most one preshared secret for all Road Warrior -systems connecting to a host. RSA Signature authentications does not -require that the responder know how to select the initiator's public key -until after the initiator's Identity Payload is decoded (using the -responder's private key, so that must be preselected). -

- -When pluto is responding to a Quick Mode negotiation via one of these -temporary connection descriptions, it may well find that the subnets -specified by the initiator don't match those in the temporary -connection description. If so, it will look for a connection with -matching subnets, its own host address, a peer address of %any -and matching identities. -If it finds one, a new temporary connection is derived from this one -and used for the Quick Mode negotiation of IPsec SAs. If it does not -find one, pluto terminates negotiation. -

- -Be sure to specify an appropriate nexthop for the responder -to send a message to the initiator: pluto has no way of guessing -it (if forwarding isn't required, use an explicit %direct as the nexthop -and the IP address of the initiator will be filled in; the obsolete -notation 0.0.0.0 is still accepted). -

- -pluto has no special provision for the initiator side. The current -(possibly dynamic) IP address and nexthop must be used in defining -connections. These must be -properly configured each time the initiator's IP address changes. -pluto has no mechanism to do this automatically. -

- -Although we call this Road Warrior Support, it could also be used to -support encrypted connections with anonymous initiators. The -responder's organization could announce the preshared secret that would be used -with unrecognized initiators and let anyone connect. Of course the initiator's -identity would not be authenticated. -

- -If any Road Warrior connections are supported, pluto cannot -reject an exchange initiated by an unknown host until it has -determined that the secret is not shared or the signature is invalid. -This must await the -third Main Mode message from the initiator. If no Road Warrior -connection is supported, the first message from an unknown source -would be rejected. This has implications for ease of debugging -configurations and for denial of service attacks. -

- -Although a Road Warrior connection must be initiated by the mobile -side, the other side can and will rekey using the temporary connection -it has created. If the Road Warrior wishes to be able to disconnect, -it is probably wise to set --keyingtries to 1 in the -connection on the non-mobile side to prevent it trying to rekey the -connection. Unfortunately, there is no mechanism to unroute the -connection automatically. -  -

Debugging

- -

- -pluto accepts several optional arguments, useful mostly for debugging. -Except for --interface, each should appear at most once. -

-
--interface interfacename
-specifies that the named real public network interface should be considered. -The interface name specified should not be ipsecN. -If the option doesn't appear, all interfaces are considered. -To specify several interfaces, use the option once for each. -One use of this option is to specify which interface should be used -when two or more share the same IP address. -
--ikeport port-number
-changes the UDP port that pluto will use -(default, specified by IANA: 500) -
--ctlbase path
-basename for control files. -path.ctl is the socket through which whack communicates with -pluto. -path.pid is the lockfile to prevent multiple pluto instances. -The default is /var/run/pluto). -
--secretsfile file
-specifies the file for authentication secrets -(default: /etc/ipsec.secrets). -This name is subject to ``globbing'' as in sh(1), -so every file with a matching name is processed. -Quoting is generally needed to prevent the shell from doing the globbing. -
--adns pathname
-
--lwdnsq pathname
-specifies where to find pluto's helper program for asynchronous DNS lookup. -pluto can be built to use one of two helper programs: _pluto_adns -or lwdnsq. You must use the program for which it was built. -By default, pluto will look for the program in -$IPSEC_DIR (if that environment variable is defined) or, failing that, -in the same directory as pluto. -
--nofork
-disable ``daemon fork'' (default is to fork). In addition, after the -lock file and control socket are created, print the line ``Pluto -initialized'' to standard out. -
--noklips
-don't actually implement negotiated IPsec SAs -
--uniqueids
-if this option has been selected, whenever a new ISAKMP SA is -established, any connection with the same Peer ID but a different -Peer IP address is unoriented (causing all its SAs to be deleted). -This helps clean up dangling SAs when a connection is lost and -then regained at another IP address. -
--stderrlog
-log goes to standard out {default is to use syslogd(8)) -
-

- -For example -

-
pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500 --nofork --noklips --stderrlog
-
-

- -lets one test pluto without using the superuser account. -

- -pluto is willing to produce a prodigious amount of debugging -information. To do so, it must be compiled with -DDEBUG. There are -several classes of debugging output, and pluto may be directed to -produce a selection of them. All lines of -debugging output are prefixed with ``| '' to distinguish them from error -messages. -

- -When pluto is invoked, it may be given arguments to specify -which classes to output. The current options are: -

-
--debug-raw
-show the raw bytes of messages -
--debug-crypt
-show the encryption and decryption of messages -
--debug-parsing
-show the structure of input messages -
--debug-emitting
-show the structure of output messages -
--debug-control
-show pluto's decision making -
--debug-lifecycle
-[this option is temporary] log more detail of lifecycle of SAs -
--debug-klips
-show pluto's interaction with KLIPS -
--debug-dns
-show pluto's interaction with DNS for KEY and TXT records -
--debug-oppo
-show why pluto didn't find a suitable DNS TXT record to authorize opportunistic initiation -
--debug-all
-all of the above -
--debug-private
-allow debugging output with private keys. -
--debug-none
-none of the above -
-

- -The debug form of the -whack command will change the selection in a running -pluto. -If a connection name is specified, the flags are added whenever -pluto has identified that it is dealing with that connection. -Unfortunately, this is often part way into the operation being observed. -

- -For example, to start a pluto with a display of the structure of input -and output: -

-
-pluto --debug-emitting --debug-parsing -
-

- -To later change this pluto to only display raw bytes: -

-
-whack --debug-raw -
-

- -For testing, SSH's IKE test page is quite useful: -

-
-http://isakmp-test.ssh.fi/ -
-

- -Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA -is established. This allows future IPsec SA's to be negotiated -directly. If one of the IKEs is restarted, the other may try to use -the ISAKMP SA but the new IKE won't know about it. This can lead to -much confusion. pluto is not yet smart enough to get out of such a -mess. -  -

Pluto's Behaviour When Things Go Wrong

- -

- -When pluto doesn't understand or accept a message, it just -ignores the message. It is not yet capable of communicating the -problem to the other IKE daemon (in the future it might use -Notifications to accomplish this in many cases). It does log a diagnostic. -

- -When pluto gets no response from a message, it resends the same -message (a message will be sent at most three times). This is -appropriate: UDP is unreliable. -

- -When pluto gets a message that it has already seen, there are many -cases when it notices and discards it. This too is appropriate for UDP. -

- -Combine these three rules, and you can explain many apparently -mysterious behaviours. In a pluto log, retrying isn't usually the -interesting event. The critical thing is either earlier (pluto -got a message which it didn't like and so ignored, so it was still -awaiting an acceptable message and got impatient) or on the other -system (pluto didn't send a reply because it wasn't happy with -the previous message). -  -

Notes

- -

- -If pluto is compiled without -DKLIPS, it negotiates Security -Associations but never ask the kernel to put them in place and never -makes routing changes. This allows pluto to be tested on systems -without KLIPS, but makes it rather useless. -

- -Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA. -The IKE protocol lets the destination of the SA choose the SPI. -The range 0 to 0xFF is reserved for IANA. -Pluto also avoids choosing an SPI in the range 0x100 to 0xFFF, -leaving these SPIs free for manual keying. -Remember that the peer, if not pluto, may well chose -SPIs in this range. -  -

Policies

- -

- -This catalogue of policies may be of use when trying to configure -Pluto and another IKE implementation to interoperate. -

- -In Phase 1, only Main Mode is supported. We are not sure that -Aggressive Mode is secure. For one thing, it does not support -identity protection. It may allow more severe Denial Of Service -attacks. -

- -No Informational Exchanges are supported. These are optional and -since their delivery is not assured, they must not matter. -It is the case that some IKE implementations won't interoperate -without Informational Exchanges, but we feel they are broken. -

- -No Informational Payloads are supported. These are optional, but -useful. It is of concern that these payloads are not authenticated in -Phase 1, nor in those Phase 2 messages authenticated with HASH(3). -

-
*
-Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) -are supported. -Group MODP768 (1) is not supported because it is too weak. -
*
-Host authetication can be done by RSA Signatures or Pre-Shared -Secrets. -
*
-3DES CBC (Cypher Block Chaining mode) is the only encryption -supported, both for ISAKMP SAs and IPSEC SAs. -
*
-MD5 and SHA1 hashing are supported for packet authentication in both -kinds of SAs. -
*
-The ESP, AH, or AH plus ESP are supported. If, and only if, AH and -ESP are combined, the ESP need not have its own authentication -component. The selection is controlled by the --encrypt and ---authenticate flags. -
*
-Each of these may be combined with IPCOMP Deflate compression, -but only if the potential connection specifies compression and only -if KLIPS is configured with IPCOMP support. -
*
-The IPSEC SAs may be tunnel or transport mode, where appropriate. -The --tunnel flag controls this when pluto is initiating. -
*
-When responding to an ISAKMP SA proposal, the maximum acceptable -lifetime is eight hours. The default is one hour. There is no -minimum. The --ikelifetime flag controls this when pluto -is initiating. -
*
-When responding to an IPSEC SA proposal, the maximum acceptable -lifetime is one day. The default is eight hours. There is no -minimum. The --ipseclifetime flag controls this when pluto -is initiating. -
*
-PFS is acceptable, and will be proposed if the --pfs flag was -specified. The DH group proposed will be the same as negotiated for -Phase 1. -
-  -

SIGNALS

- -

- -Pluto responds to SIGHUP by issuing a suggestion that ``whack ---listen'' might have been intended. -

- -Pluto exits when it recieves SIGTERM. -  -

EXIT STATUS

- -

- -pluto normally forks a daemon process, so the exit status is -normally a very preliminary result. -

-
0
-means that all is OK so far. -
1
-means that something was wrong. -
10
-means that the lock file already exists. -
-

- -If whack detects a problem, it will return an exit status of 1. -If it received progress messages from pluto, it returns as status -the value of the numeric prefix from the last such message -that was not a message sent to syslog or a comment -(but the prefix for success is treated as 0). -Otherwise, the exit status is 0. -  -

FILES

- -/var/run/pluto.pid -
- -/var/run/pluto.ctl -
- -/etc/ipsec.secrets -
- -$IPSEC_LIBDIR/_pluto_adns -
- -$IPSEC_EXECDIR/lwdnsq -
- -/dev/urandom -  -

ENVIRONMENT

- -IPSEC_LIBDIR -
- -IPSEC_EXECDIR -
- -IPSECmyid -  -

SEE ALSO

- -

- -The rest of the FreeS/WAN distribution, in particular ipsec(8). -

- -ipsec_auto(8) is designed to make using pluto more pleasant. -Use it! -

- -ipsec.secrets(5) - -describes the format of the secrets file. -

- -ipsec_atoaddr(3), part of the FreeS/WAN distribution, describes the -forms that IP addresses may take. -ipsec_atosubnet(3), part of the FreeS/WAN distribution, describes the -forms that subnet specifications. -

- -For more information on IPsec, the mailing list, and the relevant -documents, see: -

-
- -http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html - -
-

- -At the time of writing, the most relevant IETF RFCs are: -

-
-RFC2409 The Internet Key Exchange (IKE) -
-RFC2408 Internet Security Association and Key Management Protocol (ISAKMP) -
-RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP -
-

- -The FreeS/WAN web site <htp://www.freeswan.org> -and the mailing lists described there. -  -

HISTORY

- -This code is released under the GPL terms. -See the accompanying file COPYING-2.0 for more details. -The GPL does NOT apply to those pieces of code written by others -which are included in this distribution, except as noted by the -individual authors. -

- -This software was originally written -for the FreeS/WAN project -<http://www.freeswan.org> -by Angelos D. Keromytis -(angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens, Greece. -Thanks go to John Ioannidis for his help. -

- -It is currently (2000) -being developed and maintained by D. Hugh Redelmeier -(hugh@mimosa.com), in Canada. The regulations of Greece and Canada -allow us to make the code freely redistributable. -

- -Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial -version of the code supporting PFS. -

- -Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion -<ponion@srd.bt.co.uk> added the PFKEY2 support. -

- -We gratefully acknowledge that we use parts of Eric Young's libdes -package; see ../libdes/COPYRIGHT. -  -

BUGS

- -pluto - -is a work-in-progress. It currently has many limitations. -For example, it ignores notification messages that it receives, and -it generates only Delete Notifications and those only for IPSEC SAs. -

- -pluto does not support the Commit Flag. -The Commit Flag is a bad feature of the IKE protocol. -It isn't protected -- neither encrypted nor authenticated. -A man in the middle could turn it on, leading to DoS. -We just ignore it, with a warning. -This should let us interoperate with -implementations that insist on it, with minor damage. -

- -pluto does not check that the SA returned by the Responder -is actually one that was proposed. It only checks that the SA is -acceptable. The difference is not large, but can show up in attributes -such as SA lifetime. -

- -There is no good way for a connection to be automatically terminated. -This is a problem for Road Warrior and Opportunistic connections. -The --dontrekey option does prevent the SAs from -being rekeyed on expiry. -Additonally, if a Road Warrior connection has a client subnet with a fixed IP -address, a negotiation with that subnet will cause any other -connection instantiations with that same subnet to be unoriented -(deleted, in effect). -See also the --uniqueids option for an extension of this. -

- -When pluto sends a message to a peer that has disappeared, -pluto receives incomplete information from the kernel, so it -logs the unsatisfactory message ``some IKE message we sent has been -rejected with ECONNREFUSED (kernel supplied no details)''. John -Denker suggests that this command is useful for tracking down the -source of these problems: -
- -       tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0
-
- -Substitute your public interface for eth0 if it is different. -

- -The word ``authenticate'' is used for two different features. We must -authenticate each IKE peer to the other. This is an important task of -Phase 1. Each packet must be authenticated, both in IKE and in IPsec, -and the method for IPsec is negotiated as an AH SA or part of an ESP SA. -Unfortunately, the protocol has no mechanism for authenticating the Phase 2 -identities. -

- -Bugs should be reported to the <users@lists.freeswan.org> mailing list. -Caution: we cannot accept -actual code from US residents, or even US citizens living outside the -US, because that would bring FreeS/WAN under US export law. Some -other countries cause similar problems. In general, we would prefer -that you send detailed problem reports rather than code: we want -FreeS/WAN to be unquestionably freely exportable, which means being -very careful about where the code comes from, and for a small bug fix, -that is often more time-consuming than just reinventing the fix -ourselves. -

- -

- 

Index

-
-
NAME
-
SYNOPSIS
-
DESCRIPTION
-
-
IKE's Job
-
Pluto
-
Before Running Pluto
-
Setting up KLIPS for pluto
-
ipsec.secrets file
-
Running Pluto
-
Pluto's Internal State
-
Using Whack
-
Examples
-
The updown command
-
Rekeying
-
Selecting a Connection When Responding: Road Warrior Support
-
Debugging
-
Pluto's Behaviour When Things Go Wrong
-
Notes
-
Policies
-
-
SIGNALS
-
EXIT STATUS
-
FILES
-
ENVIRONMENT
-
SEE ALSO
-
HISTORY
-
BUGS
-
-
-This document was created by -man2html, -using the manual pages.
-Time: 21:40:18 GMT, November 11, 2003 - - diff --git a/doc/src/draft-richardson-ipsec-opportunistic.html b/doc/src/draft-richardson-ipsec-opportunistic.html deleted file mode 100644 index 87a13365a..000000000 --- a/doc/src/draft-richardson-ipsec-opportunistic.html +++ /dev/null @@ -1,2456 +0,0 @@ -Opportunistic Encryption using The Internet Key Exchange (IKE) - - - -
 TOC 
-
- - - - - -
Independent submissionM. Richardson
Internet-DraftSSW
Expires: November 19, 2003D. Redelmeier
 Mimosa
 May 21, 2003
-

Opportunistic Encryption using The Internet Key Exchange (IKE)
-
draft-richardson-ipsec-opportunistic-11.txt
- - -

Status of this Memo

-

-This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026.

-

-Internet-Drafts are working documents of the Internet Engineering -Task Force (IETF), its areas, and its working groups. -Note that other groups may also distribute working documents as -Internet-Drafts.

-

-Internet-Drafts are draft documents valid for a maximum of six months -and may be updated, replaced, or obsoleted by other documents at any time. -It is inappropriate to use Internet-Drafts as reference material or to cite -them other than as "work in progress."

-

-The list of current Internet-Drafts can be accessed at -http://www.ietf.org/ietf/1id-abstracts.txt.

-

-The list of Internet-Draft Shadow Directories can be accessed at -http://www.ietf.org/shadow.html.

-

-This Internet-Draft will expire on November 19, 2003.

- -

Copyright Notice

-

-Copyright (C) The Internet Society (2003). All Rights Reserved.

- -

Abstract

- -

-This document describes opportunistic encryption (OE) using the Internet Key -Exchange (IKE) and IPsec. -Each system administrator adds new -resource records to his or her Domain Name System (DNS) to support -opportunistic encryption. The objective is to allow encryption for secure communication without -any pre-arrangement specific to the pair of systems involved. - -

-

-DNS is used to distribute the public keys of each -system involved. This is resistant to passive attacks. The use of DNS -Security (DNSSEC) secures this system against active attackers as well. - -

-

-As a result, the administrative overhead is reduced -from the square of the number of systems to a linear dependence, and it becomes -possible to make secure communication the default even -when the partner is not known in advance. - -

-

-This document is offered up as an Informational RFC. - -


 -
 TOC 
-

Table of Contents

-
    -1.  -Introduction
     -2.  -Overview
     -3.  -Specification
     -4.  -Impacts on IKE
     -5.  -DNS issues
     -6.  -Network address translation interaction
     -7.  -Host implementations
     -8.  -Multi-homing
     -9.  -Failure modes
     -10.  -Unresolved issues
     -11.  -Examples
     -12.  -Security considerations
     -13.  -IANA Considerations
     -14.  -Acknowledgments
     -§  -Normative references
     -§  -Authors' Addresses
     -§  -Full Copyright Statement
     -
-
- -
 -
 TOC 
-

1. Introduction

- -

1.1 Motivation

- -

-The objective of opportunistic encryption is to allow encryption without -any pre-arrangement specific to the pair of systems involved. Each -system administrator adds -public key information to DNS records to support opportunistic -encryption and then enables this feature in the nodes' IPsec stack. -Once this is done, any two such nodes can communicate securely. - -

-

-This document describes opportunistic encryption as designed and -mostly implemented by the Linux FreeS/WAN project. -For project information, see http://www.freeswan.org. - -

-

-The Internet Architecture Board (IAB) and Internet Engineering -Steering Group (IESG) have taken a strong stand that the Internet -should use powerful encryption to provide security and -privacy [4]. -The Linux FreeS/WAN project attempts to provide a practical means to implement this policy. - -

-

-The project uses the IPsec, ISAKMP/IKE, DNS and DNSSEC -protocols because they are -standardized, widely available and can often be deployed very easily -without changing hardware or software or retraining users. - -

-

-The extensions to support opportunistic encryption are simple. No -changes to any on-the-wire formats are needed. The only changes are to -the policy decision making system. This means that opportunistic -encryption can be implemented with very minimal changes to an existing -IPsec implementation. - -

-

-Opportunistic encryption creates a "fax effect". The proliferation -of the fax machine was possible because it did not require that everyone -buy one overnight. Instead, as each person installed one, the value -of having one increased - as there were more people that could receive faxes. -Once opportunistic encryption is installed it -automatically recognizes -other boxes using opportunistic encryption, without any further configuration -by the network -administrator. So, as opportunistic encryption software is installed on more -boxes, its value -as a tool increases. - -

-

-This document describes the infrastructure to permit deployment of -Opportunistic Encryption. - -

-

-The term S/WAN is a trademark of RSA Data Systems, and is used with permission -by this project. - -

-

1.2 Types of network traffic

- -

- To aid in understanding the relationship between security processing and IPsec - we divide network traffic into four categories: - -

-
* Deny:
-
networks to which traffic is always forbidden. -
-
* Permit:
-
networks to which traffic in the clear is permitted. -
-
* Opportunistic tunnel:
-
networks to which traffic is encrypted if possible, but otherwise is in the clear - or fails depending on the default policy in place. - -
-
* Configured tunnel:
-
networks to which traffic must be encrypted, and traffic in the clear is never permitted. -
-

-

-

-Traditional firewall devices handle the first two categories. No authentication is required. -The permit policy is currently the default on the Internet. - -

-

-This document describes the third category - opportunistic tunnel, which is -proposed as the new default for the Internet. - -

-

- Category four, encrypt traffic or drop it, requires authentication of the - end points. As the number of end points is typically bounded and is typically - under a single authority, arranging for distribution of - authentication material, while difficult, does not require any new - technology. The mechanism described here provides an additional way to - distribute the authentication materials, that of a public key method that does not - require deployment of an X.509 based infrastructure. - -

-

-Current Virtual Private Networks can often be replaced by an "OE paranoid" -policy as described herein. - -

-

1.3 Peer authentication in opportunistic encryption

- -

- Opportunistic encryption creates tunnels between nodes that - are essentially strangers. This is done without any prior bilateral - arrangement. - There is, therefore, the difficult question of how one knows to whom one is - talking. - -

-

- One possible answer is that since no useful - authentication can be done, none should be tried. This mode of operation is - named "anonymous encryption". An active man-in-the-middle attack can be - used to thwart the privacy of this type of communication. - Without peer authentication, there is no way to prevent this kind of attack. - -

-

-Although a useful mode, anonymous encryption is not the goal of this -project. Simpler methods are available that can achieve anonymous -encryption only, but authentication of the peer is a desireable goal. -The latter is achieved through key distribution in DNS, leveraging upon -the authentication of the DNS in DNSSEC. - -

-

- Peers are, therefore, authenticated with DNSSEC when available. Local policy -determines how much trust to extend when DNSSEC is not available. - -

-

- However, an essential premise of building private connections with - strangers is that datagrams received through opportunistic tunnels - are no more special than datagrams that arrive in the clear. - Unlike in a VPN, these datagrams should not be given any special - exceptions when it comes to auditing, further authentication or - firewalling. - -

-

- When initiating outbound opportunistic encryption, local - configuration determines what happens if tunnel setup fails. It may be that - the packet goes out in the clear, or it may be dropped. - -

-

1.4 Use of RFC2119 terms

- -

- The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, - SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this - document, are to be interpreted as described in [5] -

-
 -
 TOC 
-

2. Overview

- -

2.1 Reference diagram

-
- - -

The following network diagram is used in the rest of - this document as the canonical diagram: -

-                          [Q]  [R]          
-                           .    .              AS2                 
-  [A]----+----[SG-A].......+....+.......[SG-B]-------[B]
-         |                 ......
-     AS1 |                 ..PI..
-         |                 ......
-  [D]----+----[SG-D].......+....+.......[C] AS3
-             
-
-
- -

-

 Reference Network Diagram 
- -

- In this diagram, there are four end-nodes: A, B, C and D. - There are three gateways, SG-A, SG-B, SG-D. A, D, SG-A and SG-D are part - of the same administrative authority, AS1. SG-A and SG-D are on two different exit - paths from organization 1. SG-B/B is an independent organization, AS2. - Nodes Q and R are nodes on the Internet. PI is the Public - Internet ("The Wild"). - -

-

2.2 Terminology

- -

- The following terminology is used in this document: - -

-
-
Security gateway:
-
a system that performs IPsec tunnel - mode encapsulation/decapsulation. [SG-x] in the diagram. -
-
Alice:
-
node [A] in the diagram. When an IP address is needed, this is 192.1.0.65. -
-
Bob:
-
node [B] in the diagram. When an IP address is needed, this is 192.2.0.66. -
-
Carol:
-
node [C] in the diagram. When an IP address is needed, this is 192.1.1.67. -
-
Dave:
-
node [D] in the diagram. When an IP address is needed, this is 192.3.0.68. -
-
SG-A:
-
Alice's security gateway. Internally it is 192.1.0.1, externally it is 192.1.1.4. -
-
SG-B:
-
Bob's security gateway. Internally it is 192.2.0.1, externally it is 192.1.1.5. -
-
SG-D:
-
Dave's security gateway. Also Alice's backup security gateway. Internally it is 192.3.0.1, externally it is 192.1.1.6. -
-
-
-
A single dash represents clear-text datagrams. -
-
=
-
An equals sign represents phase 2 (IPsec) cipher-text - datagrams. -
-
~
-
A single tilde represents clear-text phase 1 datagrams. -
-
#
-
A hash sign represents phase 1 (IKE) cipher-text - datagrams. -
-
.
-
A period represents an untrusted network of unknown - type. -
-
Configured tunnel:
-
a tunnel that - is directly and deliberately hand configured on participating gateways. - Configured tunnels are typically given a higher level of - trust than opportunistic tunnels. -
-
Road warrior tunnel:
-
a configured tunnel connecting one - node with a fixed IP address and one node with a variable IP address. - A road warrior (RW) connection must be initiated by the - variable node, since the fixed node cannot know the - current address for the road warrior. -
-
Anonymous encryption:
-
- the process of encrypting a session without any knowledge of who the - other parties are. No authentication of identities is done. -
-
Opportunistic encryption:
-
- the process of encrypting a session with authenticated knowledge of - who the other parties are. -
-
Lifetime:
-
- the period in seconds (bytes or datagrams) for which a security - association will remain alive before needing to be re-keyed. -
-
Lifespan:
-
- the effective time for which a security association remains useful. A - security association with a lifespan shorter than its lifetime would - be removed when no longer needed. A security association with a - lifespan longer than its lifetime would need to be re-keyed one or - more times. -
-
Phase 1 SA:
-
an ISAKMP/IKE security association sometimes - referred to as a keying channel. -
-
Phase 2 SA:
-
an IPsec security association. -
-
Tunnel:
-
another term for a set of phase 2 SA (one in each direction). -
-
NAT:
-
Network Address Translation - (see [20]). -
-
NAPT:
-
Network Address and Port Translation - (see [20]). -
-
AS:
-
an autonomous system (AS) is a group of systems (a network) that - are under the administrative control of a single organization. -
-
Default-free zone:
-
- a set of routers that maintain a complete set of routes to - all currently reachable destinations. Having such a list, these routers - never make use of a default route. A datagram with a destination address - not matching any route will be dropped by such a router. - -
-

-

2.3 Model of operation

- -

-The opportunistic encryption security gateway (OE gateway) is a regular -gateway node as described in [2] section 2.4 and -[3] with the additional capabilities described here and -in [7]. -The algorithm described here provides a way to determine, for each datagram, -whether or not to encrypt and tunnel the datagram. Two important things -that must be determined are whether or not to encrypt and tunnel and, if -so, the destination address or name of the tunnel end point which should be used. - -

-

2.3.1 Tunnel authorization

- -

-The OE gateway determines whether or not to create a tunnel based on -the destination address of each packet. Upon receiving a packet with a destination -address not recently seen, the OE gateway performs a lookup in DNS for an -authorization resource record (see Use of TXT delegation record). The record is located using -the IP address to perform a search in the in-addr.arpa (IPv4) or ip6.arpa -(IPv6) maps. If an authorization record is found, the OE gateway -interprets this as a request for a tunnel to be formed. - -

-

2.3.2 Tunnel end-point discovery

- -

-The authorization resource record also provides the address or name of the tunnel -end point which should be used. - -

-

-The record may also provide the public RSA key of the tunnel end point -itself. This is provided for efficiency only. If the public RSA key is not -present, the OE gateway performs a second lookup to find a KEY -resource record for the end point address or name. - -

-

-Origin and integrity protection of the resource records is provided by -DNSSEC ([16]). Restriction on unauthenticated TXT delegation records -documents an optional restriction on the tunnel end point if DNSSEC signatures -are not available for the relevant records. - -

-

2.3.3 Caching of authorization results

- -

-The OE gateway maintains a cache, in the forwarding plane, of -source/destination pairs for which opportunistic encryption has been -attempted. This cache maintains a record of whether or not OE was -successful so that subsequent datagrams can be forwarded properly -without additional delay. - -

-

-Successful negotiation of OE instantiates a new security association. -Failure to negotiate OE results in creation of a -forwarding policy entry either to drop or transmit in the clear future -datagrams. This negative cache is necessary to avoid the possibly lengthy process of repeatedly looking -up the same information. - -

-

-The cache is timed out periodically, as described in Renewal and teardown. -This removes entries that are no longer -being used and permits the discovery of changes in authorization policy. - -

-
 -
 TOC 
-

3. Specification

- -

-The OE gateway is modeled to have a forwarding plane and a control -plane. A control channel, such as PF_KEY, connects the two planes. -(See [6].) -The forwarding plane performs per datagram operations. The control plane -contains a keying -daemon, such as ISAKMP/IKE, and performs all authorization, peer authentication and -key derivation functions. - -

-

3.1 Datagram state machine

- -

-Let the OE gateway maintain a collection of objects -- a superset of the -security policy database (SPD) specified in [7]. For -each combination of source and destination address, an SPD -object exists in one of five following states. -Prior to forwarding each datagram, the -responder uses the source and destination addresses to pick an entry from the SPD. -The SPD then determines if and how the packet is forwarded. - -

-

3.1.1 Non-existent policy

- -

-If the responder does not find an entry, then this policy applies. -The responder creates an entry with an initial state of "hold policy" and requests -keying material from the keying daemon. The responder does not forward the datagram, -rather it attaches the datagram to the SPD entry as the "first" datagram and retains it -for eventual transmission in a new state. - - -

-

3.1.2 Hold policy

- -

-The responder requests keying material. If the interface to the keying -system is lossy (PF_KEY, for instance, can be), the implementation -SHOULD include a mechanism to retransmit the -keying request at a rate limited to less than 1 request per second. -The responder does not forward the datagram. It attaches the -datagram to the SPD entry as the "last" datagram where it is retained -for eventual transmission. If there is -a datagram already so stored, then that already stored datagram is discarded. - -

-

-Because the "first" datagram is probably a TCP SYN packet, the -responder retains the "first" datagram in an attempt to avoid waiting for a -TCP retransmit. The responder retains the "last" -datagram in deference to streaming protocols that find it useful to know -how much data has been lost. These are recommendations to -decrease latency. There are no operational requirements for this. - -

-

3.1.3 Pass-through policy

- -

-The responder forwards the datagram using the normal forwarding table. -The responder enters this state only by command from the keying daemon, -and upon entering this state, also forwards the "first" and "last" datagrams. - -

-

3.1.4 Deny policy

- -

-The responder discards the datagram. The responder enters this state only by -command -from the keying daemon, and upon entering this state, discards the "first" -and "last" datagrams. -Local administration decides if further datagrams cause ICMP messages -to be generated (i.e. ICMP Destination Unreachable, Communication -Administratively Prohibited. type=3, code=13). - -

-

3.1.5 Encrypt policy

- -

-The responder encrypts the datagram using the indicated security association database -(SAD) entry. The responder enters this state only by command from the keying daemon, and upon entering -this state, releases and forwards the "first" and "last" datagrams using the -new encrypt policy. - -

-

-If the associated SAD entry expires because of byte, packet or time limits, then -the entry returns to the Hold policy, and an expire message is sent to the keying daemon. - -

-

-All states may be created directly by the keying daemon while acting as a -responder. - -

-

3.2 Keying state machine - initiator

- -

-Let the keying daemon maintain a collection of objects. Let them be -called "connections" or "conn"s. There are two categories of -connection objects: classes and instances. A class represents an -abstract policy - what could be. An instance represents an actual connection - -what is implemented at the time. - -

-

-Let there be two further subtypes of connections: keying channels (Phase -1 SAs) and data channels (Phase 2 SAs). Each data channel object may have -a corresponding SPD and SAD entry maintained by the datagram state machine. - -

-

-For the purposes of opportunistic encryption, there MUST, at least, be -connection classes known as "deny", "always-clear-text", "OE-permissive", and -"OE-paranoid". -The latter two connection classes define a set of source and/or destination -addresses for which opportunistic encryption will be attempted. The administrator MAY set policy -options in a number of additional places. An implementation MAY create additional connection classes to further refine -these policies. - -

-

-The simplest system may need only the "OE-permissive" connection, and would -list its own (single) IP address as the source address of this policy and -the wild-card address 0.0.0.0/0 as the destination IPv4 address. That is, the -simplest policy is to try opportunistic encryption with all destinations. - -

-

-The distinction between permissive and paranoid OE use will become clear -in the state transition differences. In general a permissive OE will, on -failure, install a pass-through policy, while a paranoid OE will, on failure, -install a drop policy. - -

-

-In this description of the keying machine's state transitions, the states -associated with the keying system itself are omitted because they are best documented in the keying system -([8], -[9] and [10] for ISAKMP/IKE), -and the details are keying system specific. Opportunistic encryption is not -dependent upon any specific keying protocol, but this document does provide -requirements for those using ISAKMP/IKE to assure that implementations inter-operate. - -

-

-The state transitions that may be involved in communicating with the -forwarding plane are omitted. PF_KEY and similar protocols have their own -set of states required for message sends and completion notifications. - -

-

-Finally, the retransmits and recursive lookups that are normal for DNS are -not included in this description of the state machine. - -

-

3.2.1 Nonexistent connection

- -

-There is no connection instance for a given source/destination address pair. -Upon receipt of a request for keying material for this -source/destination pair, the initiator searches through the connection classes to -determine the most appropriate policy. Upon determining an appropriate -connection class, an instance object is created of that type. -Both of the OE types result in a potential OE connection. - -

-

Failure to find an appropriate connection class results in an -administrator defined default. - -

-

-In each case, when the initiator finds an appropriate class for the new flow, -an instance connection is made of the class which matched. - -

-

3.2.2 Clear-text connection

- -

-The non-existent connection makes a transition to this state when an -always-clear-text class is instantiated, or when an OE-permissive -connection fails. During the transition, the initiator creates a pass-through -policy object in the forwarding plane for the appropriate flow. - -

-

-Timing out is the only way to leave this state -(see Expiring connection). - -

-

3.2.3 Deny connection

- -

-The empty connection makes a transition to this state when a -deny class is instantiated, or when an OE-paranoid connection fails. -During the transition, the initiator creates a deny policy object in the forwarding plane -for the appropriate flow. - -

-

-Timing out is the only way to leave this state -(see Expiring connection). - -

-

3.2.4 Potential OE connection

- -

-The empty connection makes a transition to this state when one of either OE class is instantiated. -During the transition to this state, the initiator creates a hold policy object in the -forwarding plane for the appropriate flow. - -

-

-In addition, when making a transition into this state, DNS lookup is done in -the reverse-map for a TXT delegation resource record (see Use of TXT delegation record). -The lookup key is the destination address of the flow. - -

-

-There are three ways to exit this state: - -

    -
  1. DNS lookup finds a TXT delegation resource record. -
    2. -
  2. DNS lookup does not find a TXT delegation resource record. -
    3. -
  3. DNS lookup times out. -
    4. -

-

-

-Based upon the results of the DNS lookup, the potential OE connection makes a -transition to the pending OE connection state. The conditions for a -successful DNS look are: - -

    -
  1. DNS finds an appropriate resource record -
    2. -
  2. It is properly formatted according to Use of TXT delegation record -
    3. -
  3. if DNSSEC is enabled, then the signature has been vouched for. -
    4. -

- -Note that if the initiator does not find the public key -present in the TXT delegation record, then the public key must -be looked up as a sub-state. Only successful completion of all the -DNS lookups is considered a success. - -

-

-If DNS lookup does not find a resource record or DNS times out, then the -initiator considers the receiver not OE capable. If this is an OE-paranoid instance, -then the potential OE connection makes a transition to the deny connection state. -If this is an OE-permissive instance, then the potential OE connection makes a transition to the -clear-text connection state. - -

-

-If the initiator finds a resource record but it is not properly formatted, or -if DNSSEC is -enabled and reports a failure to authenticate, then the potential OE -connection should make a -transition to the deny connection state. This action SHOULD be logged. If the -administrator wishes to override this transition between states, then an -always-clear class can be installed for this flow. An implementation MAY make -this situation a new class. - -

-

3.2.4.1 Restriction on unauthenticated TXT delegation records

- -

-An implementation SHOULD also provide an additional administrative control -on delegation records and DNSSEC. This control would apply to delegation -records (the TXT records in the reverse-map) that are not protected by -DNSSEC. -Records of this type are only permitted to delegate to their own address as -a gateway. When this option is enabled, an active attack on DNS will be -unable to redirect packets to other than the original destination. - -

-

3.2.5 Pending OE connection

- -

-The potential OE connection makes a transition to this state when -the initiator determines that all the information required from the DNS lookup is present. -Upon entering this state, the initiator attempts to initiate keying to the gateway -provided. - -

-

-Exit from this state occurs either with a successfully created IPsec SA, or -with a failure of some kind. Successful SA creation results in a transition -to the key connection state. - -

-

-Three failures have caused significant problems. They are clearly not the -only possible failures from keying. - -

-

-Note that if there are multiple gateways available in the TXT delegation -records, then a failure can only be declared after all have been -tried. Further, creation of a phase 1 SA does not constitute success. A set -of phase 2 SAs (a tunnel) is considered success. - -

-

-The first failure occurs when an ICMP port unreachable is consistently received -without any other communication, or when there is silence from the remote -end. This usually means that either the gateway is not alive, or the -keying daemon is not functional. For an OE-permissive connection, the initiator makes a transition -to the clear-text connection but with a low lifespan. For an OE-pessimistic connection, -the initiator makes a transition to the deny connection again with a low lifespan. The lifespan in both -cases is kept low because the remote gateway may -be in the process of rebooting or be otherwise temporarily unavailable. - -

-

-The length of time to wait for the remote keying daemon to wake up is -a matter of some debate. If there is a routing failure, 5 minutes is usually long enough for the network to -re-converge. Many systems can reboot in that amount of -time as well. However, 5 minutes is far too long for most users to wait to -hear that they can not connect using OE. Implementations SHOULD make this a -tunable parameter. - -

-

-The second failure occurs after a phase 1 SA has been created, but there is -either no response to the phase 2 proposal, or the initiator receives a -negative notify (the notify must be -authenticated). The remote gateway is not prepared to do OE at this time. -As before, the initiator makes a transition to the clear-text or the deny -connection based upon connection class, but this -time with a normal lifespan. - -

-

-The third failure occurs when there is signature failure while authenticating -the remote gateway. This can occur when there has been a -key roll-over, but DNS has not caught up. In this case again, the initiator makes a -transition to the clear-text or the deny connection based -upon the connection class. However, the lifespan depends upon the remaining -time to live in the DNS. (Note that DNSSEC signed resource records have a different -expiry time than non-signed records.) - -

-

3.2.6 Keyed connection

- -

-The pending OE connection makes a transition to this state when -session keying material (the phase 2 SAs) is derived. The initiator creates an encrypt -policy in the forwarding plane for this flow. - -

-

-There are three ways to exit this state. The first is by receipt of an -authenticated delete message (via the keying channel) from the peer. This is -normal teardown and results in a transition to the expired connection state. - -

-

-The second exit is by expiry of the forwarding plane keying material. This -starts a re-key operation with a transition back to pending OE -connection. In general, the soft expiry occurs with sufficient time left -to continue to use the keys. A re-key can fail, which may -result in the connection failing to clear-text or deny as -appropriate. In the event of a failure, the forwarding plane -policy does not change until the phase 2 SA (IPsec SA) reaches its -hard expiry. - -

-

-The third exit is in response to a negotiation from a remote -gateway. If the forwarding plane signals the control plane that it has received an -unknown SPI from the remote gateway, or an ICMP is received from the remote gateway -indicating an unknown SPI, the initiator should consider that -the remote gateway has rebooted or restarted. Since these -indications are easily forged, the implementation must -exercise care. The initiator should make a cautious -(rate-limited) attempt to re-key the connection. - -

-

3.2.7 Expiring connection

- -

-The initiator will periodically place each of the deny, clear-text, and keyed -connections into this -sub-state. See Renewal and teardown for more details of how often this -occurs. -The initiator queries the forwarding plane for last use time of the -appropriate -policy. If the last use time is relatively recent, then the connection -returns to the -previous deny, clear-text or keyed connection state. If not, then the -connection enters -the expired connection state. - -

-

-The DNS query and answer that lead to the expiring connection state are also -examined. The DNS query may become stale. (A negative, i.e. no such record, answer -is valid for the period of time given by the MINIMUM field in an attached SOA -record. See [12] section 4.3.4.) -If the DNS query is stale, then a new query is made. If the results change, then the connection -makes a transition to a new state as described in potential OE connection state. - -

-

-Note that when considering how stale a connection is, both outgoing SPD and -incoming SAD must be queried as some flows may be unidirectional for some time. - -

-

-Also note that the policy at the forwarding plane is not updated unless there -is a conclusion that there should be a change. - -

-

3.2.8 Expired connection

- -

-Entry to this state occurs when no datagrams have been forwarded recently via the -appropriate SPD and SAD objects. The objects in the forwarding plane are -removed (logging any final byte and packet counts if appropriate) and the -connection instance in the keying plane is deleted. - -

-

-The initiator sends an ISAKMP/IKE delete to clean up the phase 2 SAs as described in -Renewal and teardown. - -

-

-Whether or not to delete the phase 1 SAs -at this time is left as a local implementation issue. Implementations -that do delete the phase 1 SAs MUST send authenticated delete messages to -indicate that they are doing so. There is an advantage to keeping -the phase 1 SAs until they expire - they may prove useful again in the -near future. - -

-

3.3 Keying state machine - responder

- -

-The responder has a set of objects identical to those of the initiator. - -

-

-The responder receives an invitation to create a keying channel from an initiator. - -

-

3.3.1 Unauthenticated OE peer

- -

-Upon entering this state, the responder starts a DNS lookup for a KEY record for the -initiator. -The responder looks in the reverse-map for a KEY record for the initiator if the -initiator has offered an ID_IPV4_ADDR, and in the forward map if the -initiator has offered an ID_FQDN type. (See [8] section -4.6.2.1.) - -

-

-The responder exits this state upon successful receipt of a KEY from DNS, and use of the key -to verify the signature of the initiator. - -

-

-Successful authentication of the peer results in a transition to the -authenticated OE Peer state. - -

-

-Note that the unauthenticated OE peer state generally occurs in the middle of the key negotiation -protocol. It is really a form of pseudo-state. - -

-

3.3.2 Authenticated OE Peer

- -

-The peer will eventually propose one or more phase 2 SAs. The responder uses the source and -destination address in the proposal to -finish instantiating the connection state -using the connection class table. -The responder MUST search for an identical connection object at this point. - -

-

-If an identical connection is found, then the responder deletes the old instance, -and the new object makes a transition to the pending OE connection state. This means -that new ISAKMP connections with a given peer will always use the latest -instance, which is the correct one if the peer has rebooted in the interim. - -

-

-If an identical connection is not found, then the responder makes the transition according to the -rules given for the initiator. - -

-

-Note that if the initiator is in OE-paranoid mode and the responder is in -either always-clear-text or deny, then no communication is possible according -to policy. An implementation is permitted to create new types of policies -such as "accept OE but do not initiate it". This is a local matter. - -

-

3.4 Renewal and teardown

- -

3.4.1 Aging

- -

-A potentially unlimited number of tunnels may exist. In practice, only a few -tunnels are used during a period of time. Unused tunnels MUST, therefore, be -torn down. Detecting when tunnels are no longer in use is the subject of this section. - -

-

-There are two methods for removing tunnels: explicit deletion or expiry. - -

-

-Explicit deletion requires an IKE delete message. As the deletes -MUST be authenticated, both ends of the tunnel must maintain the -key channel (phase 1 ISAKMP SA). An implementation which refuses to either maintain or -recreate the keying channel SA will be unable to use this method. - -

-

-The tunnel expiry method, simply allows the IKE daemon to -expire normally without attempting to re-key it. - -

-

-Regardless of which method is used to remove tunnels, the implementation requires -a method to determine if the tunnel is still in use. The specifics are a -local matter, but the FreeS/WAN project uses the following criteria. These -criteria are currently implemented in the key management daemon, but could -also be implemented at the SPD layer using an idle timer. - -

-

-Set a short initial (soft) lifespan of 1 minute since many net flows last -only a few seconds. - -

-

-At the end of the lifespan, check to see if the tunnel was used by -traffic in either direction during the last 30 seconds. If so, assign a -longer tentative lifespan of 20 minutes after which, look again. If the -tunnel is not in use, then close the tunnel. - -

-

-The expiring state in the key management -system (see Expiring connection) implements these timeouts. -The timer above may be in the forwarding plane, -but then it must be re-settable. - -

-

-The tentative lifespan is independent of re-keying; it is just the time when -the tunnel's future is next considered. -(The term lifespan is used here rather than lifetime for this reason.) -Unlike re-keying, this tunnel use check is not costly and should happen -reasonably frequently. - -

-

-A multi-step back-off algorithm is not considered worth the effort here. - -

-

-If the security gateway and the client host are the -same and not a Bump-in-the-Stack or Bump-in-the-Wire implementation, tunnel -teardown decisions MAY pay attention to TCP connection status as reported -by the local TCP layer. A still-open TCP connection is almost a guarantee that more traffic is -expected. Closing of the only TCP connection through a tunnel is a -strong hint that no more traffic is expected. - -

-

3.4.2 Teardown and cleanup

- -

-Teardown should always be coordinated between the two ends of the tunnel by -interpreting and sending delete notifications. There is a -detailed sub-state in the expired connection state of the key manager that -relates to retransmits of the delete notifications, but this is considered to -be a keying system detail. - -

-

-On receiving a delete for the outbound SAs of a tunnel (or some subset of -them), tear down the inbound ones also and notify the remote end with a -delete. If the local system receives a delete for a tunnel which is no longer in -existence, then two delete messages have crossed paths. Ignore the delete. -The operation has already been completed. Do not generate any messages in this -situation. - -

-

-Tunnels are to be considered as bidirectional entities, even though the -low-level protocols don't treat them this way. - -

-

-When the deletion is initiated locally, rather than as a -response to a received delete, send a delete for (all) the -inbound SAs of a tunnel. If the local system does not receive a responding delete -for the outbound SAs, try re-sending the original -delete. Three tries spaced 10 seconds apart seems a reasonable -level of effort. A failure of the other end to respond after 3 attempts, -indicates that the possibility of further communication is unlikely. Remove the outgoing SAs. -(The remote system may be a mobile node that is no longer present or powered on.) - -

-

-After re-keying, transmission should switch to using the new -outgoing SAs (ISAKMP or IPsec) immediately, and the old leftover -outgoing SAs should be cleared out promptly (delete should be sent -for the outgoing SAs) rather than waiting for them to expire. This -reduces clutter and minimizes confusion for the operator doing diagnostics. - -

-
 -
 TOC 
-

4. Impacts on IKE

- -

4.1 ISAKMP/IKE protocol

- -

- The IKE wire protocol needs no modifications. The major changes are - implementation issues relating to how the proposals are interpreted, and from - whom they may come. - -

-

- As opportunistic encryption is designed to be useful between peers without - prior operator configuration, an IKE daemon must be prepared to negotiate - phase 1 SAs with any node. This may require a large amount of resources to - maintain cookie state, as well as large amounts of entropy for nonces, - cookies and so on. - -

-

- The major changes to support opportunistic encryption are at the IKE daemon - level. These changes relate to handling of key acquisition requests, lookup - of public keys and TXT records, and interactions with firewalls and other - security facilities that may be co-resident on the same gateway. - -

-

4.2 Gateway discovery process

- -

- In a typical configured tunnel, the address of SG-B is provided - via configuration. Furthermore, the mapping of an SPD entry to a gateway is - typically a 1:1 mapping. When the 0.0.0.0/0 SPD entry technique is used, then - the mapping to a gateway is determined by the reverse DNS records. - -

-

- The need to do a DNS lookup and wait for a reply will typically introduce a - new state and a new event source (DNS replies) to IKE. Although a -synchronous DNS request can be implemented for proof of concept, experience -is that it can cause very high latencies when a queue of queries must -all timeout in series. - -

-

- Use of an asynchronous DNS lookup will also permit overlap of DNS lookups with - some of the protocol steps. - -

-

4.3 Self identification

- -

- SG-A will have to establish its identity. Use an - IPv4 ID in phase 1. - -

-

There are many situations where the administrator of SG-A may not be - able to control the reverse DNS records for SG-A's public IP address. - Typical situations include dialup connections and most residential-type broadband Internet access - (ADSL, cable-modem) connections. In these situations, a fully qualified domain - name that is under the control of SG-A's administrator may be used - when acting as an initiator only. - The FQDN ID should be used in phase 1. See Use of FQDN IDs - for more details and restrictions. - -

-

4.4 Public key retrieval process

- -

- Upon receipt of a phase 1 SA proposal with either an IPv4 (IPv6) ID or - an FQDN ID, an IKE daemon needs to examine local caches and - configuration files to determine if this is part of a configured tunnel. - If no configured tunnels are found, then the implementation should attempt to retrieve - a KEY record from the reverse DNS in the case of an IPv4/IPv6 ID, or - from the forward DNS in the case of FQDN ID. - -

-

- It is reasonable that if other non-local sources of policy are used - (COPS, LDAP), they be consulted concurrently but some - clear ordering of policy be provided. Note that due to variances in - latency, implementations must wait for positive or negative replies from all sources - of policy before making any decisions. - -

-

4.5 Interactions with DNSSEC

- -

- The implementation described (1.98) neither uses DNSSEC directly to - explicitly verify the authenticity of zone information, nor uses the NXT - records to provide authentication of the absence of a TXT or KEY - record. Rather, this implementation uses a trusted path to a DNSSEC - capable caching resolver. - -

-

- To distinguish between an authenticated and an unauthenticated DNS - resource record, a stub resolver capable of returning DNSSEC - information MUST be used. - -

-

4.6 Required proposal types

- -

4.6.1 Phase 1 parameters

- -

- Main mode MUST be used. - -

-

- The initiator MUST offer at least one proposal using some combination - of: 3DES, HMAC-MD5 or HMAC-SHA1, DH group 2 or 5. Group 5 SHOULD be - proposed first. - [11] -

-

- The initiator MAY offer additional proposals, but the cipher MUST not - be weaker than 3DES. The initiator SHOULD limit the number of proposals - such that the IKE datagrams do not need to be fragmented. - -

-

- The responder MUST accept one of the proposals. If any configuration - of the responder is required then the responder is not acting in an - opportunistic way. - -

-

- SG-A SHOULD use an ID_IPV4_ADDR (ID_IPV6_ADDR for IPv6) of the external - interface of SG-A for phase 1. (There is an exception, see Use of FQDN IDs.) The authentication method MUST be RSA public key signatures. - The RSA key for SG-A SHOULD be placed into a DNS KEY record in - the reverse space of SG-A (i.e. using in-addr.arpa). - -

-

4.6.2 Phase 2 parameters

- -

- SG-A MUST propose a tunnel between Alice and Bob, using 3DES-CBC - mode, MD5 or SHA1 authentication. Perfect Forward Secrecy MUST be specified. - -

-

- Tunnel mode MUST be used. - -

-

- Identities MUST be ID_IPV4_ADDR_SUBNET with the mask being /32. - -

-

- Authorization for SG-A to act on Alice's behalf is determined by - looking for a TXT record in the reverse-map at Alice's address. - -

-

- Compression SHOULD NOT be mandatory. It may be offered as an option. - -

-
 -
 TOC 
-

5. DNS issues

- -

5.1 Use of KEY record

- -

- In order to establish their own identities, SG-A and SG-B SHOULD publish - their public keys in their reverse DNS via - DNSSEC's KEY record. - See section 3 of RFC 2535[16]. - -

-

-

For example: -

-KEY 0x4200 4 1 AQNJjkKlIk9...nYyUkKK8
-
- -
-
0x4200:
-
The flag bits, indicating that this key is prohibited - for confidentiality use (it authenticates the peer only, a separate - Diffie-Hellman exchange is used for - confidentiality), and that this key is associated with the non-zone entity - whose name is the RR owner name. No other flags are set. -
-
4:
-
This indicates that this key is for use by IPsec. -
-
1:
-
An RSA key is present. -
-
AQNJjkKlIk9...nYyUkKK8:
-
The public key of the host as described in [17]. -
-

-

-

Use of several KEY records allows for key rollover. The SIG Payload in - IKE phase 1 SHOULD be accepted if the public key given by any KEY RR - validates it. - -

-

5.2 Use of TXT delegation record

- -

-Alice publishes a TXT record to provide authorization for SG-A to act on -Alice's behalf. - -Bob publishes a TXT record to provide authorization for SG-B to act on Bob's -behalf. - -These records are located in the reverse DNS (in-addr.arpa) for their -respective IP addresses. The reverse DNS SHOULD be secured by DNSSEC, when -it is deployed. DNSSEC is required to defend against active attacks. - -

-

- If Alice's address is P.Q.R.S, then she can authorize another node to - act on her behalf by publishing records at: -

-
-S.R.Q.P.in-addr.arpa
-
-

- -

-

- The contents of the resource record are expected to be a string that - uses the following syntax, as suggested in [15]. - (Note that the reply to query may include other TXT resource - records used by other applications.) - -

- -

-
-X-IPsec-Server(P)=A.B.C.D KEY
-
-

-
 Format of reverse delegation record 

- -

-
-
P:
-
Specifies a precedence for this record. This is - similar to MX record preferences. Lower numbers have stronger - preference. - -
-
A.B.C.D:
-
Specifies the IP address of the Security Gateway - for this client machine. - -
-
KEY:
-
Is the encoded RSA Public key of the Security - Gateway. The key is provided here to avoid a second DNS lookup. If this - field is absent, then a KEY resource record should be looked up in the - reverse-map of A.B.C.D. The key is transmitted in base64 format. - -
-

-

- The pieces of the record are separated by any whitespace - (space, tab, newline, carriage return). An ASCII space SHOULD - be used. - -

-

- In the case where Alice is located at a public address behind a - security gateway that has no fixed address (or no control over its - reverse-map), then Alice may delegate to a public key by domain name. - -

- -

-
-X-IPsec-Server(P)=@FQDN KEY
-
-

-
 Format of reverse delegation record (FQDN version) 

- -

-
-
P:
-
Is as above. - -
-
FQDN:
-
Specifies the FQDN that the Security Gateway - will identify itself with. - -
-
KEY:
-
Is the encoded RSA Public key of the Security - Gateway. -
-

-

- If there is more than one such TXT record with strongest (lowest - numbered) precedence, one Security Gateway is picked arbitrarily from - those specified in the strongest-preference records. - -

-

5.2.1 Long TXT records

- -

- When packed into transport format, TXT records which are longer than 255 - characters are divided into smaller <character-strings>. - (See [13] section 3.3 and 3.3.14.) These MUST - be reassembled into a single string for processing. - Whitespace characters in the base64 encoding are to be ignored. - -

-

5.2.2 Choice of TXT record

- -

- It has been suggested to use the KEY, OPT, CERT, or KX records - instead of a TXT record. None is satisfactory. - -

-

The KEY RR has a protocol field which could be used to indicate a new protocol, -and an algorithm field which could be used to - indicate different contents in the key data. However, the KEY record - is clearly not intended for storing what are really authorizations, - it is just for identities. Other uses have been discouraged. - -

-

OPT resource records, as defined in [14] are not - intended to be used for storage of information. They are not to be loaded, - cached or forwarded. They are, therefore, inappropriate for use here. - -

-

- CERT records [18] can encode almost any set of - information. A custom type code could be used permitting any suitable - encoding to be stored, not just X.509. According to - the RFC, the certificate RRs are to be signed internally which may add undesirable -and unnecessary bulk. Larger DNS records may require TCP instead of UDP transfers. - -

-

- At the time of protocol design, the CERT RR was not widely deployed and - could not be counted upon. Use of CERT records will be investigated, - and may be proposed in a future revision of this document. - -

-

- KX records are ideally suited for use instead of TXT records, but had not been deployed at - the time of implementation. - -

-

5.3 Use of FQDN IDs

- -

- Unfortunately, not every administrator has control over the contents - of the reverse-map. Where the initiator (SG-A) has no suitable reverse-map, the - authorization record present in the reverse-map of Alice may refer to a - FQDN instead of an IP address. - -

-

- In this case, the client's TXT record gives the fully qualified domain - name (FQDN) in place of its security gateway's IP address. - The initiator should use the ID_FQDN ID-payload in phase 1. - A forward lookup for a KEY record on the FQDN must yield the - initiator's public key. - -

-

- This method can also be used when the external address of SG-A is - dynamic. - -

-

- If SG-A is acting on behalf of Alice, then Alice must still delegate - authority for SG-A to do so in her reverse-map. When Alice and SG-A - are one and the same (i.e. Alice is acting as an end-node) then there - is no need for this when initiating only. -

-

However, Alice must still delegate to herself if she wishes others to - initiate OE to her. See Format of reverse delegation record (FQDN version). - -

-

5.4 Key roll-over

- -

-Good cryptographic hygiene says that one should replace public/private key pairs -periodically. Some administrators may wish to do this as often as daily. Typical DNS -propagation delays are determined by the SOA Resource Record MINIMUM -parameter, which controls how long DNS replies may be cached. For reasonable -operation of DNS servers, administrators usually want this value to be at least several -hours, sometimes as a long as a day. This presents a problem - a new key MUST -not be used prior to it propagating through DNS. - -

-

-This problem is dealt with by having the Security Gateway generate a new -public/private key pair at least MINIMUM seconds in advance of using it. It -then adds this key to the DNS (both as a second KEY record and in additional TXT -delegation records) at key generation time. Note: only one key is allowed in -each TXT record. - -

-

-When authenticating, all gateways MUST have available all public keys -that are found in DNS for this entity. This permits the authenticating end -to check both the key for "today" and the key for "tomorrow". Note that it is -the end which is creating the signature (possesses the private key) that -determines which key is to be used. - -

-
 -
 TOC 
-

6. Network address translation interaction

- -

- There are no fundamentally new issues for implementing opportunistic encryption - in the presence of network address translation. Rather there are - only the regular IPsec issues with NAT traversal. - -

-

- There are several situations to consider for NAT. - -

-

6.1 Co-located NAT/NAPT

- -

- If SG-A is also performing network address translation on - behalf of Alice, then the packet should be translated prior to - being subjected to opportunistic encryption. This is in contrast to - typically configured tunnels which often exist to bridge islands of - private network address space. SG-A will use the translated source - address for phase 2, and so SG-B will look up that address to - confirm SG-A's authorization. - -

-

In the case of NAT (1:1), the address space into which the - translation is done MUST be globally unique, and control over the - reverse-map is assumed. - Placing of TXT records is possible. - -

-

In the case of NAPT (m:1), the address will be SG-A. The ability to get - KEY and TXT records in place will again depend upon whether or not - there is administrative control over the reverse-map. This is - identical to situations involving a single host acting on behalf of - itself. - - FQDN style can be used to get around a lack of a reverse-map for - initiators only. - -

-

6.2 SG-A behind NAT/NAPT

- -

- If there is a NAT or NAPT between SG-A and SG-B, then normal IPsec - NAT traversal rules apply. In addition to the transport problem - which may be solved by other mechanisms, there - is the issue of what phase 1 and phase 2 IDs to use. While FQDN could - be used during phase 1 for SG-A, there is no appropriate ID for phase 2 - that permits SG-B to determine that SG-A is in fact authorized to speak for Alice. - -

-

6.3 Bob is behind a NAT/NAPT

- -

- If Bob is behind a NAT (perhaps SG-B), then there is, in fact, no way for - Alice to address a packet to Bob. Not only is opportunistic encryption - impossible, but it is also impossible for Alice to initiate any - communication to Bob. It may be possible for Bob to initiate in such - a situation. This creates an asymmetry, but this is common for - NAPT. - -

-
 -
 TOC 
-

7. Host implementations

- -

- When Alice and SG-A are components of the same system, they are - considered to be a host implementation. The packet sequence scenario remains unchanged. - -

-

- Components marked Alice are the upper layers (TCP, UDP, the - application), and SG-A is the IP layer. - -

-

- Note that tunnel mode is still required. - -

-

- As Alice and SG-A are acting on behalf of themselves, no TXT based delegation - record is necessary for Alice to initiate. She can rely on FQDN in a - forward map. This is particularly attractive to mobile nodes such as - notebook computers at conferences. - To respond, Alice/SG-A will still need an entry in Alice's reverse-map. - -

-
 -
 TOC 
-

8. Multi-homing

- -

-If there are multiple paths between Alice and Bob (as illustrated in -the diagram with SG-D), then additional DNS records are required to establish -authorization. - -

-

-In Reference Network Diagram, Alice has two ways to -exit her network: SG-A and SG-D. Previously SG-D has been ignored. Postulate -that there are routers between Alice and her set of security gateways -(denoted by the + signs and the marking of an autonomous system number for -Alice's network). Datagrams may, therefore, travel to either SG-A or SG-D en -route to Bob. - -

-

-As long as all network connections are in good order, it does not matter how -datagrams exit Alice's network. When they reach either security gateway, the -security gateway will find the TXT delegation record in Bob's reverse-map, -and establish an SA with SG-B. - -

-

-SG-B has no problem establishing that either of SG-A or SG-D may speak for -Alice, because Alice has published two equally weighted TXT delegation records: -

- -

-
-X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q==
-X-IPsec-Server(10)=192.1.1.6 AAJN...j8r9==
-
-

-
 Multiple gateway delegation example for Alice 

- -

-

-Alice's routers can now do any kind of load sharing needed. Both SG-A and SG-D send datagrams addressed to Bob through -their tunnel to SG-B. - -

-

-Alice's use of non-equal weight delegation records to show preference of one gateway over another, has relevance only when SG-B -is initiating to Alice. - -

-

-If the precedences are the same, then SG-B has a more difficult time. It -must decide which of the two tunnels to use. SG-B has no information about -which link is less loaded, nor which security gateway has more cryptographic -resources available. SG-B, in fact, has no knowledge of whether both gateways -are even reachable. - -

-

-The Public Internet's default-free zone may well know a good route to Alice, -but the datagrams that SG-B creates must be addressed to either SG-A or SG-D; -they can not be addressed to Alice directly. - -

-

-SG-B may make a number of choices: - -

    -
  1. It can ignore the problem and round robin among the tunnels. This - causes losses during times when one or the other security gateway is - unreachable. If this worries Alice, she can change the weights in her - TXT delegation records. -
    2. -
  2. It can send to the gateway from which it most recently received datagrams. - This assumes that routing and reachability are symmetrical. -
    3. -
  3. It can listen to BGP information from the Internet to decide which - system is currently up. This is clearly much more complicated, but if SG-B is already participating - in the BGP peering system to announce Bob, the results data may already - be available to it. -
    4. -
  4. It can refuse to negotiate the second tunnel. (It is unclear whether or -not this is even an option.) -
    5. -
  5. It can silently replace the outgoing portion of the first tunnel with the -second one while still retaining the incoming portions of both. SG-B can, -thus, accept datagrams from either SG-A or SG-D, but -send only to the gateway that most recently re-keyed with it. -
    6. -

-

-

-Local policy determines which choice SG-B makes. Note that even if SG-B has perfect -knowledge about the reachability of SG-A and SG-D, Alice may not be reachable -from either of these security gateways because of internal reachability -issues. - -

-

-FreeS/WAN implements option 5. Implementing a different option is -being considered. The multi-homing aspects of OE are not well developed and may -be the subject of a future document. - -

-
 -
 TOC 
-

9. Failure modes

- -

9.1 DNS failures

- -

- If a DNS server fails to respond, local policy decides - whether or not to permit communication in the clear as embodied in - the connection classes in Keying state machine - initiator. - It is easy to mount a denial of service attack on the DNS server - responsible for a particular network's reverse-map. - Such an attack may cause all communication with that network to go in - the clear if the policy is permissive, or fail completely - if the policy is paranoid. Please note that this is an active attack. - -

-

- There are still many networks - that do not have properly configured reverse-maps. Further, if the policy is not to communicate, - the above denial of service attack isolates the target network. Therefore, the decision of whether -or not to permit communication in the clear MUST be a matter of local policy. - -

-

9.2 DNS configured, IKE failures

- -

- DNS records claim that opportunistic encryption should - occur, but the target gateway either does not respond on port 500, or - refuses the proposal. This may be because of a crash or reboot, a - faulty configuration, or a firewall filtering port 500. - -

-

- The receipt of ICMP port, host or network unreachable - messages indicates a potential problem, but MUST NOT cause communication - to fail - immediately. ICMP messages are easily forged by attackers. If such a - forgery caused immediate failure, then an active attacker could easily - prevent any - encryption from ever occurring, possibly preventing all communication. - -

-

- In these situations a clear log should be produced - and local policy should dictate if communication is then - permitted in the clear. - -

-

9.3 System reboots

- -

-Tunnels sometimes go down because the remote end crashes, -disconnects, or has a network link break. In general there is no -notification of this. Even in the event of a crash and successful reboot, -other SGs don't hear about it unless the rebooted SG has specific -reason to talk to them immediately. Over-quick response to temporary -network outages is undesirable. Note that a tunnel can be torn -down and then re-established without any effect visible to the user -except a pause in traffic. On the other hand, if one end reboots, -the other end can't get datagrams to it at all (except via -IKE) until the situation is noticed. So a bias toward quick -response is appropriate even at the cost of occasional -false alarms. - -

-

-A mechanism for recovery after reboot is a topic of current research and is not specified in this -document. - -

-

-A deliberate shutdown should include an attempt, using deletes, to notify all other SGs -currently connected by phase 1 SAs that communication is -about to fail. Again, a remote SG will assume this is a teardown. Attempts by the -remote SGs to negotiate new tunnels as replacements should be ignored. When possible, -SGs should attempt to preserve information about currently-connected SGs in non-volatile storage, so -that after a crash, an Initial-Contact can be sent to previous partners to -indicate loss of all previously established connections. - -

-
 -
 TOC 
-

10. Unresolved issues

- -

10.1 Control of reverse DNS

- -

- The method of obtaining information by reverse DNS lookup causes - problems for people who cannot control their reverse DNS - bindings. This is an unresolved problem in this version, and is out - of scope. - -

-
 -
 TOC 
-

11. Examples

- -

11.1 Clear-text usage (permit policy)

- -

-Two example scenarios follow. In the first example GW-A -(Gateway A) and GW-B (Gateway B) have always-clear-text policies, and in the second example they have an OE -policy. - -


- -
-  Alice         SG-A       DNS       SG-B           Bob
-   (1)
-    ------(2)-------------->
-    <-----(3)---------------
-   (4)----(5)----->
-                   ----------(6)------>
-                                       ------(7)----->
-                                      <------(8)------
-                   <----------(9)------
-    <----(10)-----
-   (11)----------->
-                   ----------(12)----->
-                                       -------------->
-                                      <---------------
-                   <-------------------
-    <-------------
-
-
 Timing of regular transaction 
- -

-Alice wants to communicate with Bob. Perhaps she wants to retrieve a -web page from Bob's web server. In the absence of opportunistic -encryptors, the following events occur: - -

-
(1)
-
Human or application 'clicks' with a name. -
-
(2)
-
Application looks up name in DNS to get IP address. -
-
(3)
-
Resolver returns A record to application. -
-
(4)
-
Application starts a TCP session or UDP session and OS sends datagram. -
-
(5)
-
Datagram is seen at first gateway from Alice (SG-A). (SG-A -makes a transition through Empty connection to always-clear connection and -instantiates a pass-through policy at the forwarding plane.) -
-
(6)
-
Datagram is seen at last gateway before Bob (SG-B). -
-
(7)
-
First datagram from Alice is seen by Bob. -
-
(8)
-
First return datagram is sent by Bob. -
-
(9)
-
Datagram is seen at Bob's gateway. (SG-B makes a transition through -Empty connection to always-clear connection and instantiates a pass-through -policy at the forwarding plane.) -
-
(10)
-
Datagram is seen at Alice's gateway. -
-
(11)
-
OS hands datagram to application. Alice sends another datagram. -
-
(12)
-
A second datagram traverses the Internet. -
-

-

-

11.2 Opportunistic encryption

- -

-In the presence of properly configured opportunistic encryptors, the -event list is extended. - -

- -

-
-  Alice          SG-A      DNS       SG-B           Bob
-   (1)
-    ------(2)-------------->
-    <-----(3)---------------
-   (4)----(5)----->+
-                  ----(5B)->
-                  <---(5C)--
-                  ~~~~~~~~~~~~~(5D)~~~>
-                  <~~~~~~~~~~~~(5E1)~~~
-                  ~~~~~~~~~~~~~(5E2)~~>
-                  <~~~~~~~~~~~~(5E3)~~~
-                  #############(5E4)##>
-                  <############(5E5)###
-                           <----(5F1)--
-                           -----(5F2)->
-                  #############(5G1)##>
-                           <----(5H1)--
-                           -----(5H2)->
-                  <############(5G2)###
-                  #############(5G3)##>
-                   ============(6)====>
-		                       ------(7)----->
-                                      <------(8)------
-                  <==========(9)======
-    <-----(10)----
-   (11)----------->
-                   ==========(12)=====>
-                                       -------------->
-                                      <---------------
-                   <===================
-    <-------------
-
-

-
 Timing of opportunistic encryption transaction 

- -
-
(1)
-
Human or application clicks with a name. -
-
(2)
-
Application initiates DNS mapping. -
-
(3)
-
Resolver returns A record to application. -
-
(4)
-
Application starts a TCP session or UDP. -
-
(5)
-
SG-A (host or SG) sees datagram to target, and buffers it. -
-
(5B)
-
SG-A asks DNS for TXT record. -
-
(5C)
-
DNS returns TXT record(s). -
-
(5D)
-
Initial IKE Main Mode Packet goes out. -
-
(5E)
-
IKE ISAKMP phase 1 succeeds. -
-
(5F)
-
SG-B asks DNS for TXT record to prove SG-A is an agent for Alice. -
-
(5G)
-
IKE phase 2 negotiation. -
-
(5H)
-
DNS lookup by responder (SG-B). -
-
(6)
-
Buffered datagram is sent by SG-A. -
-
(7)
-
Datagram is received by SG-B, decrypted, and sent to Bob. -
-
(8)
-
Bob replies, and datagram is seen by SG-B. -
-
(9)
-
SG-B already has tunnel up with SG-A, and uses it. -
-
(10)
-
SG-A decrypts datagram and gives it to Alice. -
-
(11)
-
Alice receives datagram. Sends new packet to Bob. -
-
(12)
-
SG-A gets second datagram, sees that tunnel is up, and uses it. -
-

-

-

- For the purposes of this section, we will describe only the changes that - occur between Timing of regular transaction and - Timing of opportunistic encryption transaction. This corresponds to time points 5, 6, 7, 9 and 10 on the list above. - -

-

11.2.1 (5) IPsec datagram interception

- -

- At point (5), SG-A intercepts the datagram because this source/destination pair lacks a policy -(the non-existent policy state). SG-A creates a hold policy, and buffers the datagram. SG-A requests keys from the keying daemon. - -

-

11.2.2 (5B) DNS lookup for TXT record

- -

- SG-A's IKE daemon, having looked up the source/destination pair in the connection - class list, creates a new Potential OE connection instance. SG-A starts DNS - queries. - -

-

11.2.3 (5C) DNS returns TXT record(s)

- -

- DNS returns properly formed TXT delegation records, and SG-A's IKE daemon - causes this instance to make a transition from Potential OE connection to Pending OE - connection. - -

-

- Using the example above, the returned record might contain: - -

- -

-
-X-IPsec-Server(10)=192.1.1.5 AQMM...3s1Q==
-
-

-
 Example of reverse delegation record for Bob 

- - with SG-B's IP address and public key listed. - -

-

11.2.4 (5D) Initial IKE main mode packet goes out

- -

Upon entering Pending OE connection, SG-A sends the initial ISAKMP - message with proposals. See Phase 1 parameters. - -

-

11.2.5 (5E1) Message 2 of phase 1 exchange

- -

- SG-B receives the message. A new connection instance is created in the - unauthenticated OE peer state. - -

-

11.2.6 (5E2) Message 3 of phase 1 exchange

- -

- SG-A sends a Diffie-Hellman exponent. This is an internal state of the - keying daemon. - -

-

11.2.7 (5E3) Message 4 of phase 1 exchange

- -

- SG-B responds with a Diffie-Hellman exponent. This is an internal state of the - keying protocol. - -

-

11.2.8 (5E4) Message 5 of phase 1 exchange

- -

- SG-A uses the phase 1 SA to send its identity under encryption. - The choice of identity is discussed in Phase 1 parameters. - This is an internal state of the keying protocol. - -

-

11.2.9 (5F1) Responder lookup of initiator key

- -

- SG-B asks DNS for the public key of the initiator. - DNS looks for a KEY record by IP address in the reverse-map. - That is, a KEY resource record is queried for 4.1.1.192.in-addr.arpa - (recall that SG-A's external address is 192.1.1.4). - SG-B uses the resulting public key to authenticate the initiator. See Use of KEY record for further details. - -

-

11.2.10 (5F2) DNS replies with public key of initiator

- -

-Upon successfully authenticating the peer, the connection instance makes a -transition to authenticated OE peer on SG-B. - -

-

-The format of the TXT record returned is described in -Use of TXT delegation record. - -

-

11.2.11 (5E5) Responder replies with ID and authentication

- -

- SG-B sends its ID along with authentication material. This is an internal - state for the keying protocol. - -

-

11.2.12 (5G) IKE phase 2

- -

11.2.12.1 (5G1) Initiator proposes tunnel

- -

- Having established mutually agreeable authentications (via KEY) and - authorizations (via TXT), SG-A proposes to create an IPsec tunnel for - datagrams transiting from Alice to Bob. This tunnel is established only for - the Alice/Bob combination, not for any subnets that may be behind SG-A and SG-B. - -

-

11.2.12.2 (5H1) Responder determines initiator's authority

- -

- While the identity of SG-A has been established, its authority to - speak for Alice has not yet been confirmed. SG-B does a reverse - lookup on Alice's address for a TXT record. - -

-

Upon receiving this specific proposal, SG-B's connection instance - makes a transition into the potential OE connection state. SG-B may already have an - instance, and the check is made as described above. -

-

11.2.12.3 (5H2) DNS replies with TXT record(s)

- -

- The returned key and IP address should match that of SG-A. - -

-

11.2.12.4 (5G2) Responder agrees to proposal

- -

- Should additional communication occur between, for instance, Dave and Bob using - SG-A and SG-B, a new tunnel (phase 2 SA) would be established. The phase 1 SA - may be reusable. - -

-

SG-A, having successfully keyed the tunnel, now makes a transition from - Pending OE connection to Keyed OE connection. - -

-

The responder MUST setup the inbound IPsec SAs before sending its reply. -

-

11.2.12.5 (5G3) Final acknowledgment from initiator

- -

- The initiator agrees with the responder's choice and sets up the tunnel. - The initiator sets up the inbound and outbound IPsec SAs. - -

-

- The proper authorization returned with keys prompts SG-B to make a transition - to the keyed OE connection state. - -

-

Upon receipt of this message, the responder may now setup the outbound - IPsec SAs. -

-

11.2.13 (6) IPsec succeeds, and sets up tunnel for communication between Alice and Bob

- -

- SG-A sends the datagram saved at step (5) through the newly created - tunnel to SG-B, where it gets decrypted and forwarded. - Bob receives it at (7) and replies at (8). - -

-

11.2.14 (9) SG-B already has tunnel up with G1 and uses it

- -

- At (9), SG-B has already established an SPD entry mapping Bob->Alice via a - tunnel, so this tunnel is simply applied. The datagram is encrypted to SG-A, - decrypted by SG-A and passed to Alice at (10). - -

-
 -
 TOC 
-

12. Security considerations

- -

12.1 Configured vs opportunistic tunnels

- -

- Configured tunnels are those which are setup using bilateral mechanisms: exchanging -public keys (raw RSA, DSA, PKIX), pre-shared secrets, or by referencing keys that -are in known places (distinguished name from LDAP, DNS). These keys are then used to -configure a specific tunnel. - -

-

-A pre-configured tunnel may be on all the time, or may be keyed only when needed. -The end points of the tunnel are not necessarily static: many mobile -applications (road warrior) are considered to be configured tunnels. - -

-

-The primary characteristic is that configured tunnels are assigned specific -security properties. They may be trusted in different ways relating to exceptions to -firewall rules, exceptions to NAT processing, and to bandwidth or other quality of service restrictions. - -

-

-Opportunistic tunnels are not inherently trusted in any strong way. They are -created without prior arrangement. As the two parties are strangers, there -MUST be no confusion of datagrams that arrive from opportunistic peers and -those that arrive from configured tunnels. A security gateway MUST take care -that an opportunistic peer can not impersonate a configured peer. - -

-

-Ingress filtering MUST be used to make sure that only datagrams authorized by -negotiation (and the concomitant authentication and authorization) are -accepted from a tunnel. This is to prevent one peer from impersonating another. - -

-

-An implementation suggestion is to treat opportunistic tunnel -datagrams as if they arrive on a logical interface distinct from other -configured tunnels. As the number of opportunistic tunnels that may be -created automatically on a system is potentially very high, careful attention -to scaling should be taken into account. - -

-

-As with any IKE negotiation, opportunistic encryption cannot be secure -without authentication. Opportunistic encryption relies on DNS for its -authentication information and, therefore, cannot be fully secure without -a secure DNS. Without secure DNS, opportunistic encryption can protect against passive -eavesdropping but not against active man-in-the-middle attacks. - -

-

12.2 Firewalls versus Opportunistic Tunnels

- -

- Typical usage of per datagram access control lists is to implement various -kinds of security gateways. These are typically called "firewalls". - -

-

- Typical usage of a virtual private network (VPN) within a firewall is to -bypass all or part of the access controls between two networks. Additional -trust (as outlined in the previous section) is given to datagrams that arrive -in the VPN. - -

-

- Datagrams that arrive via opportunistically configured tunnels MUST not be -trusted. Any security policy that would apply to a datagram arriving in the -clear SHOULD also be applied to datagrams arriving opportunistically. - -

-

12.3 Denial of service

- -

- There are several different forms of denial of service that an implementor - should concern themselves with. Most of these problems are shared with - security gateways that have large numbers of mobile peers (road warriors). - -

-

- The design of ISAKMP/IKE, and its use of cookies, defend against many kinds - of denial of service. Opportunism changes the assumption that if the phase 1 (ISAKMP) - SA is authenticated, that it was worthwhile creating. Because the gateway will communicate with any machine, it is - possible to form phase 1 SAs with any machine on the Internet. - -

-
 -
 TOC 
-

13. IANA Considerations

- -

- There are no known numbers which IANA will need to manage. - -

-
 -
 TOC 
-

14. Acknowledgments

- -

- Substantive portions of this document are based upon previous work by - Henry Spencer. - -

-

- Thanks to Tero Kivinen, Sandy Harris, Wes Hardarker, Robert Moskowitz, - Jakob Schlyter, Bill Sommerfeld, John Gilmore and John Denker for their - comments and constructive criticism. - -

-

- Sandra Hoffman and Bill Dickie did the detailed proof reading and editing. - -

-
 -
 TOC 
-

Normative references

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1]Redelmeier, D. and H. Spencer, "Opportunistic Encryption", paper http://www.freeswan.org/freeswan_trees/freeswan-1.91/doc/opportunism.spec, May 2001.
[2]Defense Advanced Research Projects Agency (DARPA), Information Processing Techniques Office and University of Southern California (USC)/Information Sciences Institute, "Internet Protocol", STD 5, RFC 791, September 1981.
[3]Braden, R. and J. Postel, "Requirements for Internet gateways", RFC 1009, June 1987.
[4]IAB, IESG, Carpenter, B. and F. Baker, "IAB and IESG Statement on Cryptographic Technology and the Internet", RFC 1984, August 1996.
[5]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[6]McDonald, D., Metz, C. and B. Phan, "PF_KEY Key Management API, Version 2", RFC 2367, July 1998.
[7]Kent, S. and R. Atkinson, "Security Architecture for the Internet Protocol", RFC 2401, November 1998.
[8]Piper, D., "The Internet IP Security Domain of Interpretation for ISAKMP", RFC 2407, November 1998.
[9]Maughan, D., Schneider, M. and M. Schertler, "Internet Security Association and Key Management Protocol (ISAKMP)", RFC 2408, November 1998.
[10]Harkins, D. and D. Carrel, "The Internet Key Exchange (IKE)", RFC 2409, November 1998.
[11]Kivinen, T. and M. Kojo, "More MODP Diffie-Hellman groups for IKE", RFC 3526, March 2003.
[12]Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, November 1987.
[13]Mockapetris, P., "Domain names - implementation and specification", STD 13, RFC 1035, November 1987.
[14]Vixie, P., "Extension Mechanisms for DNS (EDNS0)", RFC 2671, August 1999.
[15]Rosenbaum, R., "Using the Domain Name System To Store Arbitrary String Attributes", RFC 1464, May 1993.
[16]Eastlake, D., "Domain Name System Security Extensions", RFC 2535, March 1999.
[17]Eastlake, D., "RSA/SHA-1 SIGs and RSA KEYs in the Domain Name System (DNS)", RFC 3110, May 2001.
[18]Eastlake, D. and O. Gudmundsson, "Storing Certificates in the Domain Name System (DNS)", RFC 2538, March 1999.
[19]Durham, D., Boyle, J., Cohen, R., Herzog, S., Rajan, R. and A. Sastry, "The COPS (Common Open Policy Service) Protocol", RFC 2748, January 2000.
[20]Srisuresh, P. and M. Holdrege, "IP Network Address Translator (NAT) Terminology and Considerations", RFC 2663, August 1999.
- -
 -
 TOC 
-

Authors' Addresses

- - - - - - - - - - - - - - - - - - - - - - - - - - -
 Michael C. Richardson
 Sandelman Software Works
 470 Dawson Avenue
 Ottawa, ON K1Z 5V7
 CA
EMail: mcr@sandelman.ottawa.on.ca
URI: http://www.sandelman.ottawa.on.ca/
  
 D. Hugh Redelmeier
 Mimosa
 Toronto, ON
 CA
EMail: hugh@mimosa.com
-
 -
 TOC 
-

Full Copyright Statement

-

-Copyright (C) The Internet Society (2003). All Rights Reserved.

-

-This document and translations of it may be copied and furnished to -others, and derivative works that comment on or otherwise explain it -or assist in its implementation may be prepared, copied, published and -distributed, in whole or in part, without restriction of any kind, -provided that the above copyright notice and this paragraph are -included on all such copies and derivative works. However, this -document itself may not be modified in any way, such as by removing -the copyright notice or references to the Internet Society or other -Internet organizations, except as needed for the purpose of -developing Internet standards in which case the procedures for -copyrights defined in the Internet Standards process must be -followed, or as required to translate it into languages other than -English.

-

-The limited permissions granted above are perpetual and will not be -revoked by the Internet Society or its successors or assigns.

-

-This document and the information contained herein is provided on an -"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING -TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING -BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION -HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF -MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

-

Acknowledgement

-

-Funding for the RFC Editor function is currently provided by the -Internet Society.

- diff --git a/doc/src/draft-richardson-ipsec-opportunistic.xml b/doc/src/draft-richardson-ipsec-opportunistic.xml deleted file mode 100644 index d587df693..000000000 --- a/doc/src/draft-richardson-ipsec-opportunistic.xml +++ /dev/null @@ -1,2519 +0,0 @@ - - - - - - - - - Security - Independent submission - - Opportunistic Encryption using The Internet Key Exchange (IKE) - - - - Sandelman Software Works -
- - 470 Dawson Avenue - Ottawa - ON - K1Z 5V7 - CA - - mcr@sandelman.ottawa.on.ca - http://www.sandelman.ottawa.on.ca/ -
- - - - Mimosa -
- - Toronto - ON - CA - - hugh@mimosa.com -
- - - - - - -This document describes opportunistic encryption (OE) using the Internet Key -Exchange (IKE) and IPsec. -Each system administrator adds new -resource records to his or her Domain Name System (DNS) to support -opportunistic encryption. The objective is to allow encryption for secure communication without -any pre-arrangement specific to the pair of systems involved. - - -DNS is used to distribute the public keys of each -system involved. This is resistant to passive attacks. The use of DNS -Security (DNSSEC) secures this system against active attackers as well. - - -As a result, the administrative overhead is reduced -from the square of the number of systems to a linear dependence, and it becomes -possible to make secure communication the default even -when the partner is not known in advance. - - -This document is offered up as an Informational RFC. - - - - - - - -
- -
- - -The objective of opportunistic encryption is to allow encryption without -any pre-arrangement specific to the pair of systems involved. Each -system administrator adds -public key information to DNS records to support opportunistic -encryption and then enables this feature in the nodes' IPsec stack. -Once this is done, any two such nodes can communicate securely. - - - -This document describes opportunistic encryption as designed and -implemented by the Linux FreeS/WAN project in revisions up and including 2.00. -Note that 2.01 and beyond implements RFC3445, in a backward compatible way. -For project information, see http://www.freeswan.org. - - - -The Internet Architecture Board (IAB) and Internet Engineering -Steering Group (IESG) have taken a strong stand that the Internet -should use powerful encryption to provide security and -privacy . -The Linux FreeS/WAN project attempts to provide a practical means to implement this policy. - - - -The project uses the IPsec, ISAKMP/IKE, DNS and DNSSEC -protocols because they are -standardized, widely available and can often be deployed very easily -without changing hardware or software or retraining users. - - - -The extensions to support opportunistic encryption are simple. No -changes to any on-the-wire formats are needed. The only changes are to -the policy decision making system. This means that opportunistic -encryption can be implemented with very minimal changes to an existing -IPsec implementation. - - - -Opportunistic encryption creates a "fax effect". The proliferation -of the fax machine was possible because it did not require that everyone -buy one overnight. Instead, as each person installed one, the value -of having one increased - as there were more people that could receive faxes. -Once opportunistic encryption is installed it -automatically recognizes -other boxes using opportunistic encryption, without any further configuration -by the network -administrator. So, as opportunistic encryption software is installed on more -boxes, its value -as a tool increases. - - - -This document describes the infrastructure to permit deployment of -Opportunistic Encryption. - - - -The term S/WAN is a trademark of RSA Data Systems, and is used with permission -by this project. - - -
- -
- - To aid in understanding the relationship between security processing and IPsec - we divide network traffic into four categories: - - networks to which traffic is always forbidden. - networks to which traffic in the clear is permitted. - networks to which traffic is encrypted if possible, but otherwise is in the clear - or fails depending on the default policy in place. - - networks to which traffic -must be encrypted, and traffic in the clear is never permitted. -A Virtual Private Network (VPN) is a form of configured tunnel. - - - - - -Traditional firewall devices handle the first two categories. -No authentication is required. -The permit policy is currently the default on the Internet. - - - -This document describes the third category - opportunistic tunnel, which is -proposed as the new default for the Internet. - - - - Category four, encrypt traffic or drop it, requires authentication of the - end points. As the number of end points is typically bounded and is typically - under a single authority, arranging for distribution of - authentication material, while difficult, does not require any new - technology. The mechanism described here provides an additional way to - distribute the authentication materials, that of a public key method that does not - require deployment of an X.509 based infrastructure. - - -Current Virtual Private Networks can often be replaced by an "OE paranoid" -policy as described herein. - -
- -
- - - Opportunistic encryption creates tunnels between nodes that - are essentially strangers. This is done without any prior bilateral - arrangement. - There is, therefore, the difficult question of how one knows to whom one is - talking. - - - - One possible answer is that since no useful - authentication can be done, none should be tried. This mode of operation is - named "anonymous encryption". An active man-in-the-middle attack can be - used to thwart the privacy of this type of communication. - Without peer authentication, there is no way to prevent this kind of attack. - - - -Although a useful mode, anonymous encryption is not the goal of this -project. Simpler methods are available that can achieve anonymous -encryption only, but authentication of the peer is a desireable goal. -The latter is achieved through key distribution in DNS, leveraging upon -the authentication of the DNS in DNSSEC. - - - - Peers are, therefore, authenticated with DNSSEC when available. Local policy -determines how much trust to extend when DNSSEC is not available. - - - - However, an essential premise of building private connections with - strangers is that datagrams received through opportunistic tunnels - are no more special than datagrams that arrive in the clear. - Unlike in a VPN, these datagrams should not be given any special - exceptions when it comes to auditing, further authentication or - firewalling. - - - - When initiating outbound opportunistic encryption, local - configuration determines what happens if tunnel setup fails. It may be that - the packet goes out in the clear, or it may be dropped. - - -
- -
- - The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, - SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this - document, are to be interpreted as described in - -
- -
- -
- -
- -
- The following network diagram is used in the rest of - this document as the canonical diagram: - - [Q] [R] - . . AS2 - [A]----+----[SG-A].......+....+.......[SG-B]-------[B] - | ...... - AS1 | ..PI.. - | ...... - [D]----+----[SG-D].......+....+.......[C] AS3 - - - - - -
- - - In this diagram, there are four end-nodes: A, B, C and D. - There are three security gateways, SG-A, SG-B, SG-D. A, D, SG-A and - SG-D are part - of the same administrative authority, AS1. SG-A and SG-D are on two - different exit - paths from organization 1. SG-B/B is an independent organization, AS2. - Nodes Q and R are nodes on the Internet. PI is the Public - Internet ("The Wild"). - - -
- -
- - - The following terminology is used in this document: - - - - a system that performs IPsec tunnel - mode encapsulation/decapsulation. [SG-x] in the diagram. - node [A] in the diagram. When an IP address is needed, this is 192.1.0.65. - node [B] in the diagram. When an IP address is needed, this is 192.2.0.66. - node [C] in the diagram. When an IP address is needed, this is 192.1.1.67. - node [D] in the diagram. When an IP address is needed, this is 192.3.0.68. - Alice's security gateway. Internally it is 192.1.0.1, externally it is 192.1.1.4. - Bob's security gateway. Internally it is 192.2.0.1, externally it is 192.1.1.5. - Dave's security gateway. Also Alice's backup security gateway. Internally it is 192.3.0.1, externally it is 192.1.1.6. - A period represents an untrusted network of unknown - type. - a tunnel that - is directly and deliberately hand configured on participating gateways. - Configured tunnels are typically given a higher level of - trust than opportunistic tunnels. - - a configured tunnel connecting one - node with a fixed IP address and one node with a variable IP address. - A road warrior (RW) connection must be initiated by the - variable node, since the fixed node cannot know the - current address for the road warrior. - - - the process of encrypting a session without any knowledge of who the - other parties are. No authentication of identities is done. - - - the process of encrypting a session with authenticated knowledge of - who the other party is. - - - the period in seconds (bytes or datagrams) for which a security - association will remain alive before needing to be re-keyed. - - - the effective time for which a security association remains useful. A - security association with a lifespan shorter than its lifetime would - be removed when no longer needed. A security association with a - lifespan longer than its lifetime would need to be re-keyed one or - more times. - - an ISAKMP/IKE security association sometimes - referred to as a keying channel. - - an IPsec security association. - - another term for a set of phase 2 SA (one in each direction). - - Network Address Translation - (see ). - - Network Address and Port Translation - (see ). - - an autonomous system - - Fully-Qualified Domain Name - - - a set of routers that maintain a complete set of routes to - all currently reachable destinations. Having such a list, these routers - never make use of a default route. A datagram with a destination address - not matching any route will be dropped by such a router. - - - -
- -
- - -The opportunistic encryption security gateway (OE gateway) is a regular -gateway node as described in section 2.4 and - with the additional capabilities described here and -in . -The algorithm described here provides a way to determine, for each datagram, -whether or not to encrypt and tunnel the datagram. Two important things -that must be determined are whether or not to encrypt and tunnel and, if -so, the destination address or name of the tunnel end point which should be used. - - -
- -The OE gateway determines whether or not to create a tunnel based on -the destination address of each packet. Upon receiving a packet with a destination -address not recently seen, the OE gateway performs a lookup in DNS for an -authorization resource record (see ). The record is located using -the IP address to perform a search in the in-addr.arpa (IPv4) or ip6.arpa -(IPv6) maps. If an authorization record is found, the OE gateway -interprets this as a request for a tunnel to be formed. - -
- -
- - -The authorization resource record also provides the address or name of the tunnel -end point which should be used. - - -The record may also provide the public RSA key of the tunnel end point -itself. This is provided for efficiency only. If the public RSA key is not -present, the OE gateway performs a second lookup to find a KEY -resource record for the end point address or name. - - -Origin and integrity protection of the resource records is provided by -DNSSEC (). -documents an optional restriction on the tunnel end point if DNSSEC signatures -are not available for the relevant records. - - -
- -
- -The OE gateway maintains a cache, in the forwarding plane, of -source/destination pairs for which opportunistic encryption has been -attempted. This cache maintains a record of whether or not OE was -successful so that subsequent datagrams can be forwarded properly -without additional delay. - - - -Successful negotiation of OE instantiates a new security association. -Failure to negotiate OE results in creation of a -forwarding policy entry either to drop or transmit in the clear future -datagrams. This negative cache is necessary to avoid the possibly lengthy process of repeatedly looking -up the same information. - - - -The cache is timed out periodically, as described in . -This removes entries that are no longer -being used and permits the discovery of changes in authorization policy. - -
- -
- -
- -
- - -The OE gateway is modeled to have a forwarding plane and a control -plane. A control channel, such as PF_KEY, connects the two planes. -(See .) -The forwarding plane performs per datagram operations. The control plane -contains a keying daemon, such as ISAKMP/IKE, and performs all -authorization, peer authentication and key derivation functions. - - -
- - -Let the OE gateway maintain a collection of objects -- a superset of the -security policy database (SPD) specified in . For -each combination of source and destination address, an SPD -object exists in one of five following states. -Prior to forwarding each datagram, the responder uses the source and -destination addresses to pick an entry from the SPD. -The SPD then determines if and how the packet is forwarded. - - - - - - -
- -If the gateway does not find an entry, then this policy applies. -The gateway creates an entry with an initial state of "hold policy" and requests -keying material from the keying daemon. The gateway does not forward the datagram, -rather it SHOULD attach the datagram to the SPD entry as the "first" datagram and retain it -for eventual transmission in a new state. - - -
- -
- -The gateway requests keying material. If the interface to the keying -system is lossy (PF_KEY, for instance, can be), the implementation -SHOULD include a mechanism to retransmit the -keying request at a rate limited to less than 1 request per second. -The gateway does not forward the datagram. The gateway SHOULD attach the -datagram to the SPD entry as the "last" datagram where it is retained -for eventual transmission. -If there is a datagram already so stored, then that already stored datagram is discarded. - - -The rational behind saving the the "first" and "last" datagrams are as follows: -The "first" datagram is probably a TCP SYN packet. Once there is keying -established, the gateway will release this datagram, avoiding the need to -for the end-point to retransmit the datagram. In the case where the connection -was not a TCP connection, buyt was instead a streaming protocol or a DNS request, -the "last" datagram that was retained is likely the most recent data. The difference -between "first" and "last" may also help the end-points determine -which data awas dropped while negotiation took place. - -
- -
- -The gateway forwards the datagram using the normal forwarding table. -The gateway enters this state only by command from the keying daemon, -and upon entering this state, also forwards the "first" and "last" datagrams. - -
- -
- -The gateway discards the datagram. The gateway enters this state only by -command -from the keying daemon, and upon entering this state, discards the "first" -and "last" datagrams. -An implementation MAY provide the administator with a control to determine -if further datagrams cause ICMP messages -to be generated (i.e. ICMP Destination Unreachable, Communication -Administratively Prohibited. type=3, code=13). - -
- -
- -The gateway encrypts the datagram using the indicated security association database -(SAD) entry. The gateway enters this state only by command from the keying daemon, and upon entering -this state, releases and forwards the "first" and "last" datagrams using the -new encrypt policy. - - -If the associated SAD entry expires because of byte, packet or time limits, then -the entry returns to the Hold policy, and an expire message is sent to the keying daemon. - -
- - -All states may be created directly by the keying daemon while acting as a -gateway. - - -
- - -
- -Let the keying daemon maintain a collection of objects. Let them be -called "connections" or "conn"s. There are two categories of -connection objects: classes and instances. A class represents an -abstract policy - what could be. An instance represents an actual connection - -what is implemented at the time. - - - -Let there be two further subtypes of connections: keying channels (Phase -1 SAs) and data channels (Phase 2 SAs). Each data channel object may have -a corresponding SPD and SAD entry maintained by the datagram state machine. - - - -For the purposes of opportunistic encryption, there MUST, at least, be -connection classes known as "deny", "always-clear-text", "OE-permissive", and -"OE-paranoid". -The latter two connection classes define a set of source and/or destination -addresses for which opportunistic encryption will be attempted. -The administrator MAY set policy options in a number of additional places. -An implementation MAY create additional connection classes to further refine -these policies. - - - -The simplest system may need only the "OE-permissive" connection, and would -list its own (single) IP address as the source address of this policy and -the wild-card address 0.0.0.0/0 as the destination IPv4 address. That is, the -simplest policy is to try opportunistic encryption with all destinations. - - - -The distinction between permissive and paranoid OE use will become clear -in the state transition differences. In general a permissive OE will, on -failure, install a pass-through policy, while a paranoid OE will, on failure, -install a drop policy. - - - -In this description of the keying machine's state transitions, the states -associated with the keying system itself are omitted because they are best documented in the keying system -(, - and for ISAKMP/IKE), -and the details are keying system specific. Opportunistic encryption is not -dependent upon any specific keying protocol, but this document does provide -requirements for those using ISAKMP/IKE to assure that implementations inter-operate. - - -The state transitions that may be involved in communicating with the -forwarding plane are omitted. PF_KEY and similar protocols have their own -set of states required for message sends and completion notifications. - - -Finally, the retransmits and recursive lookups that are normal for DNS are -not included in this description of the state machine. - - - -| deny |---> expired -| connection | | for | connection | connection -`---------------' | destination `---------------' - ^ ^ | ^ - | | no record | | - | | OE-permissive V | no record - | | .---------------. | OE-paranoid - | `------------| potential OE |---------' - | | connection | ^ - | `---------------' | - | | | - | | got TXT record | DNSSEC failure - | | reply | - | V | wrong - | .---------------. | failure - | | authenticate |---------' - | | & parse TXT RR| ^ - | repeated `---------------' | - | ICMP | | - | failures | initiate IKE to | - | (short-timeout) | responder | - | V | - | phase-2 .---------------. | failure - | failure | pending |---------' - | (normal | OE | ^ - | timeout) | |invalid | phase-2 failure (short-timeout) - | | |<--.SPI | ICMP failures (normal timeout) - | | | | | - | | +=======+ |---' | - | | | IKE | | ^ | - `--------------| | states|---------------' - | +=======+ | | - `---------------' | - | IPsec SA | invalid SPI - | established | - V | rekey time - .--------------. | - | keyed |<---|-------------------------------. - | connection |----' | - `--------------' | - | timer | - | | - V | - .--------------. connection still active | - clear-text----->| expired |------------------------------------' - deny----->| connection | - `--------------' - | dead connected - deleted - V -]]> - - -
- -There is no connection instance for a given source/destination address pair. -Upon receipt of a request for keying material for this -source/destination pair, the initiator searches through the connection classes to -determine the most appropriate policy. Upon determining an appropriate -connection class, an instance object is created of that type. -Both of the OE types result in a potential OE connection. - -Failure to find an appropriate connection class results in an -administrator defined default. - - -In each case, when the initiator finds an appropriate class for the new flow, -an instance connection is made of the class which matched. - -
- -
- -The non-existent connection makes a transition to this state when an -always-clear-text class is instantiated, or when an OE-permissive -connection fails. During the transition, the initiator creates a pass-through -policy object in the forwarding plane for the appropriate flow. - - -Timing out is the only way to leave this state -(see ). - -
- -
- -The empty connection makes a transition to this state when a -deny class is instantiated, or when an OE-paranoid connection fails. -During the transition, the initiator creates a deny policy object in the forwarding plane -for the appropriate flow. - - -Timing out is the only way to leave this state -(see ). - -
- -
- -The empty connection makes a transition to this state when one of either OE class is instantiated. -During the transition to this state, the initiator creates a hold policy object in the -forwarding plane for the appropriate flow. - - -In addition, when making a transition into this state, DNS lookup is done in -the reverse-map for a TXT delegation resource record (see ). -The lookup key is the destination address of the flow. - - -There are three ways to exit this state: - -DNS lookup finds a TXT delegation resource record. -DNS lookup does not find a TXT delegation resource record. -DNS lookup times out. - - - - -Based upon the results of the DNS lookup, the potential OE connection makes a -transition to the pending OE connection state. The conditions for a -successful DNS look are: - -DNS finds an appropriate resource record -It is properly formatted according to - if DNSSEC is enabled, then the signature has been vouched for. - - -Note that if the initiator does not find the public key -present in the TXT delegation record, then the public key must -be looked up as a sub-state. Only successful completion of all the -DNS lookups is considered a success. - - -If DNS lookup does not find a resource record or DNS times out, then the -initiator considers the receiver not OE capable. If this is an OE-paranoid instance, -then the potential OE connection makes a transition to the deny connection state. -If this is an OE-permissive instance, then the potential OE connection makes a transition to the -clear-text connection state. - - -If the initiator finds a resource record but it is not properly formatted, or -if DNSSEC is -enabled and reports a failure to authenticate, then the potential OE -connection makes a -transition to the deny connection state. This action SHOULD be logged. If the -administrator wishes to override this transition between states, then an -always-clear class can be installed for this flow. An implementation MAY make -this situation a new class. - - -
- -An implementation SHOULD also provide an additional administrative control -on delegation records and DNSSEC. This control would apply to delegation -records (the TXT records in the reverse-map) that are not protected by -DNSSEC. -Records of this type are only permitted to delegate to their own address as -a gateway. When this option is enabled, an active attack on DNS will be -unable to redirect packets to other than the original destination. - - -
-
- -
- -The potential OE connection makes a transition to this state when -the initiator determines that all the information required from the DNS lookup is present. -Upon entering this state, the initiator attempts to initiate keying to the gateway -provided. - - -Exit from this state occurs either with a successfully created IPsec SA, or -with a failure of some kind. Successful SA creation results in a transition -to the key connection state. - - -Three failures have caused significant problems. They are clearly not the -only possible failures from keying. - - -Note that if there are multiple gateways available in the TXT delegation -records, then a failure can only be declared after all have been -tried. Further, creation of a phase 1 SA does not constitute success. A set -of phase 2 SAs (a tunnel) is considered success. - - -The first failure occurs when an ICMP port unreachable is consistently received -without any other communication, or when there is silence from the remote -end. This usually means that either the gateway is not alive, or the -keying daemon is not functional. For an OE-permissive connection, the initiator makes a transition -to the clear-text connection but with a low lifespan. For an OE-pessimistic connection, -the initiator makes a transition to the deny connection again with a low lifespan. The -lifespan in both -cases is kept low because the remote gateway may -be in the process of rebooting or be otherwise temporarily unavailable. - - -The length of time to wait for the remote keying daemon to wake up is -a matter of some debate. If there is a routing failure, 5 minutes is usually long -enough for the network to -re-converge. Many systems can reboot in that amount of -time as well. However, 5 minutes is far too long for most users to wait to -hear that they can not connect using OE. Implementations SHOULD make this a -tunable parameter. - - -The second failure occurs after a phase 1 SA has been created, but there is -either no response to the phase 2 proposal, or the initiator receives a -negative notify (the notify must be -authenticated). The remote gateway is not prepared to do OE at this time. -As before, the initiator makes a transition to the clear-text or the deny -connection based upon connection class, but this -time with a normal lifespan. - - -The third failure occurs when there is signature failure while authenticating -the remote gateway. This can occur when there has been a -key roll-over, but DNS has not caught up. In this case again, the initiator makes a -transition to the clear-text or the deny connection based -upon the connection class. However, the lifespan depends upon the remaining -time to live in the DNS. (Note that DNSSEC signed resource records have a different -expiry time than non-signed records.) - - - -
- -
- -The pending OE connection makes a transition to this state when -session keying material (the phase 2 SAs) is derived. The initiator creates an encrypt -policy in the forwarding plane for this flow. - - -There are three ways to exit this state. The first is by receipt of an -authenticated delete message (via the keying channel) from the peer. This is -normal teardown and results in a transition to the expired connection state. - - -The second exit is by expiry of the forwarding plane keying material. This -starts a re-key operation with a transition back to pending OE -connection. In general, the soft expiry occurs with sufficient time left -to continue to use the keys. A re-key can fail, which may -result in the connection failing to clear-text or deny as -appropriate. In the event of a failure, the forwarding plane -policy does not change until the phase 2 SA (IPsec SA) reaches its -hard expiry. - - -The third exit is in response to a negotiation from a remote -gateway. If the forwarding plane signals the control plane that it has received an -unknown SPI from the remote gateway, or an ICMP is received from the remote gateway -indicating an unknown SPI, the initiator should consider that -the remote gateway has rebooted or restarted. Since these -indications are easily forged, the implementation must -exercise care. The initiator should make a cautious -(rate-limited) attempt to re-key the connection. - -
- -
- -The initiator will periodically place each of the deny, clear-text, and keyed -connections into this -sub-state. See for more details of how often this -occurs. -The initiator queries the forwarding plane for last use time of the -appropriate -policy. If the last use time is relatively recent, then the connection -returns to the -previous deny, clear-text or keyed connection state. If not, then the -connection enters -the expired connection state. - - -The DNS query and answer that lead to the expiring connection state are also -examined. The DNS query may become stale. (A negative, i.e. no such record, answer -is valid for the period of time given by the MINIMUM field in an attached SOA -record. See section 4.3.4.) -If the DNS query is stale, then a new query is made. If the results change, then the connection -makes a transition to a new state as described in potential OE connection state. - - -Note that when considering how stale a connection is, both outgoing SPD and -incoming SAD must be queried as some flows may be unidirectional for some time. - - -Also note that the policy at the forwarding plane is not updated unless there -is a conclusion that there should be a change. - - -
-
- -Entry to this state occurs when no datagrams have been forwarded recently via the -appropriate SPD and SAD objects. The objects in the forwarding plane are -removed (logging any final byte and packet counts if appropriate) and the -connection instance in the keying plane is deleted. - - -The initiator sends an ISAKMP/IKE delete to clean up the phase 2 SAs as described in -. - - -Whether or not to delete the phase 1 SAs -at this time is left as a local implementation issue. Implementations -that do delete the phase 1 SAs MUST send authenticated delete messages to -indicate that they are doing so. There is an advantage to keeping -the phase 1 SAs until they expire - they may prove useful again in the -near future. - -
- -
- -
- -The responder has a set of objects identical to those of the initiator. - - -The responder receives an invitation to create a keying channel from an initiator. - - - - log failure - | reply | - `----+--------+---' - phase 2 | \ misformatted - proposal | `------------------> log failure - V - .----------------. - | authenticated | identical initiator - | OE peer |--------------------> initiator - `----------------' connection found state machine - | - | look for TXT record for initiator - | - V - .---------------. - | authorized |---------------------> log failure - | OE peer | - `---------------' - | - | - V - potential OE - connection in - initiator state - machine - - -$Id: draft-richardson-ipsec-opportunistic.xml,v 1.1 2004/03/15 20:35:24 as Exp $ -]]> - - -
- -Upon entering this state, the responder starts a DNS lookup for a KEY record for the -initiator. -The responder looks in the reverse-map for a KEY record for the initiator if the -initiator has offered an ID_IPV4_ADDR, and in the forward map if the -initiator has offered an ID_FQDN type. (See section -4.6.2.1.) - - -The responder exits this state upon successful receipt of a KEY from DNS, and use of the key -to verify the signature of the initiator. - - - - - -Successful authentication of the peer results in a transition to the -authenticated OE Peer state. - - -Note that the unauthenticated OE peer state generally occurs in the middle of the key negotiation -protocol. It is really a form of pseudo-state. - -
- -
- -The peer will eventually propose one or more phase 2 SAs. The responder uses the source and -destination address in the proposal to -finish instantiating the connection state -using the connection class table. -The responder MUST search for an identical connection object at this point. - - -If an identical connection is found, then the responder deletes the old instance, -and the new object makes a transition to the pending OE connection state. This means -that new ISAKMP connections with a given peer will always use the latest -instance, which is the correct one if the peer has rebooted in the interim. - - -If an identical connection is not found, then the responder makes the transition according to the -rules given for the initiator. - - -Note that if the initiator is in OE-paranoid mode and the responder is in -either always-clear-text or deny, then no communication is possible according -to policy. An implementation is permitted to create new types of policies -such as "accept OE but do not initiate it". This is a local matter. - -
- -
- -
-
- -A potentially unlimited number of tunnels may exist. In practice, only a few -tunnels are used during a period of time. Unused tunnels MUST, therefore, be -torn down. Detecting when tunnels are no longer in use is the subject of this section. - - - -There are two methods for removing tunnels: explicit deletion or expiry. - - - -Explicit deletion requires an IKE delete message. As the deletes -MUST be authenticated, both ends of the tunnel must maintain the -key channel (phase 1 ISAKMP SA). An implementation which refuses to either maintain or -recreate the keying channel SA will be unable to use this method. - - - -The tunnel expiry method simply allows the IKE daemon to -expire normally without attempting to re-key it. - - - -Regardless of which method is used to remove tunnels, the implementation MUST -a method to determine if the tunnel is still in use. The specifics are a -local matter, but the FreeS/WAN project uses the following criteria. These -criteria are currently implemented in the key management daemon, but could -also be implemented at the SPD layer using an idle timer. - - - -Set a short initial (soft) lifespan of 1 minute since many net flows last -only a few seconds. - - - -At the end of the lifespan, check to see if the tunnel was used by -traffic in either direction during the last 30 seconds. If so, assign a -longer tentative lifespan of 20 minutes after which, look again. If the -tunnel is not in use, then close the tunnel. - - - -The expiring state in the key management -system (see ) implements these timeouts. -The timer above may be in the forwarding plane, -but then it must be re-settable. - - - -The tentative lifespan is independent of re-keying; it is just the time when -the tunnel's future is next considered. -(The term lifespan is used here rather than lifetime for this reason.) -Unlike re-keying, this tunnel use check is not costly and should happen -reasonably frequently. - - - -A multi-step back-off algorithm is not considered worth the effort here. - - - -If the security gateway and the client host are the -same and not a Bump-in-the-Stack or Bump-in-the-Wire implementation, tunnel -teardown decisions MAY pay attention to TCP connection status as reported -by the local TCP layer. A still-open TCP connection is almost a guarantee that more traffic is -expected. Closing of the only TCP connection through a tunnel is a -strong hint that no more traffic is expected. - - -
- -
- - -Teardown should always be coordinated between the two ends of the tunnel by -interpreting and sending delete notifications. There is a -detailed sub-state in the expired connection state of the key manager that -relates to retransmits of the delete notifications, but this is considered to -be a keying system detail. - - - -On receiving a delete for the outbound SAs of a tunnel (or some subset of -them), tear down the inbound ones also and notify the remote end with a -delete. If the local system receives a delete for a tunnel which is no longer in -existence, then two delete messages have crossed paths. Ignore the delete. -The operation has already been completed. Do not generate any messages in this -situation. - - -Tunnels are to be considered as bidirectional entities, even though the -low-level protocols don't treat them this way. - - - -When the deletion is initiated locally, rather than as a -response to a received delete, send a delete for (all) the -inbound SAs of a tunnel. If the local system does not receive a responding delete -for the outbound SAs, try re-sending the original -delete. Three tries spaced 10 seconds apart seems a reasonable -level of effort. A failure of the other end to respond after 3 attempts, -indicates that the possibility of further communication is unlikely. Remove the outgoing SAs. -(The remote system may be a mobile node that is no longer present or powered on.) - - - -After re-keying, transmission should switch to using the new -outgoing SAs (ISAKMP or IPsec) immediately, and the old leftover -outgoing SAs should be cleared out promptly (delete should be sent -for the outgoing SAs) rather than waiting for them to expire. This -reduces clutter and minimizes confusion for the operator doing diagnostics. - - -
- -
- -
- -
- -
- - The IKE wire protocol needs no modifications. The major changes are - implementation issues relating to how the proposals are interpreted, and from - whom they may come. - - - As opportunistic encryption is designed to be useful between peers without - prior operator configuration, an IKE daemon must be prepared to negotiate - phase 1 SAs with any node. This may require a large amount of resources to - maintain cookie state, as well as large amounts of entropy for nonces, - cookies and so on. - - - The major changes to support opportunistic encryption are at the IKE daemon - level. These changes relate to handling of key acquisition requests, lookup - of public keys and TXT records, and interactions with firewalls and other - security facilities that may be co-resident on the same gateway. - -
- -
- - In a typical configured tunnel, the address of SG-B is provided - via configuration. Furthermore, the mapping of an SPD entry to a gateway is - typically a 1:1 mapping. When the 0.0.0.0/0 SPD entry technique is used, then - the mapping to a gateway is determined by the reverse DNS records. - - - The need to do a DNS lookup and wait for a reply will typically introduce a - new state and a new event source (DNS replies) to IKE. Although a -synchronous DNS request can be implemented for proof of concept, experience -is that it can cause very high latencies when a queue of queries must -all timeout in series. - - - Use of an asynchronous DNS lookup will also permit overlap of DNS lookups with - some of the protocol steps. - -
- -
- - SG-A will have to establish its identity. Use an - IPv4 ID in phase 1. - - There are many situations where the administrator of SG-A may not be - able to control the reverse DNS records for SG-A's public IP address. - Typical situations include dialup connections and most residential-type broadband Internet access - (ADSL, cable-modem) connections. In these situations, a fully qualified domain - name that is under the control of SG-A's administrator may be used - when acting as an initiator only. - The FQDN ID should be used in phase 1. See - for more details and restrictions. - -
- -
- - Upon receipt of a phase 1 SA proposal with either an IPv4 (IPv6) ID or - an FQDN ID, an IKE daemon needs to examine local caches and - configuration files to determine if this is part of a configured tunnel. - If no configured tunnels are found, then the implementation should attempt to retrieve - a KEY record from the reverse DNS in the case of an IPv4/IPv6 ID, or - from the forward DNS in the case of FQDN ID. - - - It is reasonable that if other non-local sources of policy are used - (COPS, LDAP), they be consulted concurrently but some - clear ordering of policy be provided. Note that due to variances in - latency, implementations must wait for positive or negative replies from all sources - of policy before making any decisions. - -
- -
- - The implementation described (1.98) neither uses DNSSEC directly to - explicitly verify the authenticity of zone information, nor uses the NXT - records to provide authentication of the absence of a TXT or KEY - record. Rather, this implementation uses a trusted path to a DNSSEC - capable caching resolver. - - - To distinguish between an authenticated and an unauthenticated DNS - resource record, a stub resolver capable of returning DNSSEC - information MUST be used. - - -
- - - -
- -
- - Main mode MUST be used. - - - The initiator MUST offer at least one proposal using some combination - of: 3DES, HMAC-MD5 or HMAC-SHA1, DH group 2 or 5. Group 5 SHOULD be - proposed first. - - - - The initiator MAY offer additional proposals, but the cipher MUST not - be weaker than 3DES. The initiator SHOULD limit the number of proposals - such that the IKE datagrams do not need to be fragmented. - - - The responder MUST accept one of the proposals. If any configuration - of the responder is required then the responder is not acting in an - opportunistic way. - - - The initiator SHOULD use an ID_IPV4_ADDR (ID_IPV6_ADDR for IPv6) of the external - interface of the initiator for phase 1. (There is an exception, see .) The authentication method MUST be RSA public key signatures. - The RSA key for the initiator SHOULD be placed into a DNS KEY record in - the reverse space of the initiator (i.e. using in-addr.arpa or - ip6.arpa). - -
- -
- - The initiator MUST propose a tunnel between the ultimate - sender ("Alice" or "A") and ultimate recipient ("Bob" or "B") - using 3DES-CBC - mode, MD5 or SHA1 authentication. Perfect Forward Secrecy MUST be specified. - - - Tunnel mode MUST be used. - - - Identities MUST be ID_IPV4_ADDR_SUBNET with the mask being /32. - - - Authorization for the initiator to act on Alice's behalf is determined by - looking for a TXT record in the reverse-map at Alice's IP address. - - - Compression SHOULD NOT be mandatory. It MAY be offered as an option. - -
-
- -
- -
-
- - In order to establish their own identities, security gateways SHOULD publish - their public keys in their reverse DNS via - DNSSEC's KEY record. - See section 3 of RFC 2535. - - - For example: - - - - The flag bits, indicating that this key is prohibited - for confidentiality use (it authenticates the peer only, a separate - Diffie-Hellman exchange is used for - confidentiality), and that this key is associated with the non-zone entity - whose name is the RR owner name. No other flags are set. - This indicates that this key is for use by IPsec. - An RSA key is present. - The public key of the host as described in . - - - Use of several KEY records allows for key rollover. The SIG Payload in - IKE phase 1 SHOULD be accepted if the public key given by any KEY RR - validates it. - -
- -
- -If, for example, machine Alice wishes SG-A to act on her behalf, then -she publishes a TXT record to provide authorization for SG-A to act on -Alice's behalf. Similarly for Bob and SG-B. - - - -These records are located in the reverse DNS (in-addr.arpa or ip6.arpa) for their -respective IP addresses. The reverse DNS SHOULD be secured by DNSSEC. -DNSSEC is required to defend against active attacks. - - - If Alice's address is P.Q.R.S, then she can authorize another node to - act on her behalf by publishing records at: - - - - - The contents of the resource record are expected to be a string that - uses the following syntax, as suggested in RFC1464. - (Note that the reply to query may include other TXT resource - records used by other applications.) - -
- -
- - - where the record is formed by the following fields: - - - Specifies a precedence for this record. This is - similar to MX record preferences. Lower numbers have stronger - preference. - - - Specifies the IP address of the Security Gateway - for this client machine. - - - Is the encoded RSA Public key of the Security - Gateway. The key is provided here to avoid a second DNS lookup. If this - field is absent, then a KEY resource record should be looked up in the - reverse-map of A.B.C.D. The key is transmitted in base64 format. - - - - - The fields of the record MUST be separated by whitespace. This - MAY be: space, tab, newline, or carriage return. A space is preferred. - - - - In the case where Alice is located at a public address behind a - security gateway that has no fixed address (or no control over its - reverse-map), then Alice may delegate to a public key by domain name. - -
- -
- - - - Is as above. - - - Specifies the FQDN that the Security Gateway - will identify itself with. - - - Is the encoded RSA Public key of the Security - Gateway. - - - - If there is more than one such TXT record with strongest (lowest - numbered) precedence, one Security Gateway is picked arbitrarily from - those specified in the strongest-preference records. - - -
- - When packed into transport format, TXT records which are longer than 255 - characters are divided into smaller <character-strings>. - (See section 3.3 and 3.3.14.) These MUST - be reassembled into a single string for processing. - Whitespace characters in the base64 encoding are to be ignored. - -
- -
- - It has been suggested to use the KEY, OPT, CERT, or KX records - instead of a TXT record. None is satisfactory. - - The KEY RR has a protocol field which could be used to indicate a new protocol, -and an algorithm field which could be used to - indicate different contents in the key data. However, the KEY record - is clearly not intended for storing what are really authorizations, - it is just for identities. Other uses have been discouraged. - - OPT resource records, as defined in are not - intended to be used for storage of information. They are not to be loaded, - cached or forwarded. They are, therefore, inappropriate for use here. - - - CERT records can encode almost any set of - information. A custom type code could be used permitting any suitable - encoding to be stored, not just X.509. According to - the RFC, the certificate RRs are to be signed internally which may add undesirable -and unnecessary bulk. Larger DNS records may require TCP instead of UDP transfers. - - - At the time of protocol design, the CERT RR was not widely deployed and - could not be counted upon. Use of CERT records will be investigated, - and may be proposed in a future revision of this document. - - - KX records are ideally suited for use instead of TXT records, but had not been deployed at - the time of implementation. - - -
-
- -
- - Unfortunately, not every administrator has control over the contents - of the reverse-map. Where the initiator (SG-A) has no suitable reverse-map, the - authorization record present in the reverse-map of Alice may refer to a - FQDN instead of an IP address. - - - In this case, the client's TXT record gives the fully qualified domain - name (FQDN) in place of its security gateway's IP address. - The initiator should use the ID_FQDN ID-payload in phase 1. - A forward lookup for a KEY record on the FQDN must yield the - initiator's public key. - - - This method can also be used when the external address of SG-A is - dynamic. - - - If SG-A is acting on behalf of Alice, then Alice must still delegate - authority for SG-A to do so in her reverse-map. When Alice and SG-A - are one and the same (i.e. Alice is acting as an end-node) then there - is no need for this when initiating only. - However, Alice must still delegate to herself if she wishes others to - initiate OE to her. See . - - < -
- -
- -Good cryptographic hygiene says that one should replace public/private key pairs -periodically. Some administrators may wish to do this as often as daily. Typical DNS -propagation delays are determined by the SOA Resource Record MINIMUM -parameter, which controls how long DNS replies may be cached. For reasonable -operation of DNS servers, administrators usually want this value to be at least several -hours, sometimes as a long as a day. This presents a problem - a new key MUST -not be used prior to it propagating through DNS. - - -This problem is dealt with by having the Security Gateway generate a new -public/private key pair at least MINIMUM seconds in advance of using it. It -then adds this key to the DNS (both as a second KEY record and in additional TXT -delegation records) at key generation time. Note: only one key is allowed in -each TXT record. - - -When authenticating, all gateways MUST have available all public keys -that are found in DNS for this entity. This permits the authenticating end -to check both the key for "today" and the key for "tomorrow". Note that it is -the end which is creating the signature (possesses the private key) that -determines which key is to be used. - - -
-
- - -
- - There are no fundamentally new issues for implementing opportunistic encryption - in the presence of network address translation. Rather there are - only the regular IPsec issues with NAT traversal. - - - There are several situations to consider for NAT. - -
- - If a security gateway is also performing network address translation on - behalf of an end-system, then the packet should be translated prior to - being subjected to opportunistic encryption. This is in contrast to - typically configured tunnels which often exist to bridge islands of - private network address space. The security gateway will use the translated source - address for phase 2, and so the responding security gateway will look up that address to - confirm SG-A's authorization. - - In the case of NAT (1:1), the address space into which the - translation is done MUST be globally unique, and control over the - reverse-map is assumed. - Placing of TXT records is possible. - - In the case of NAPT (m:1), the address will be the security - gateway itself. The ability to get - KEY and TXT records in place will again depend upon whether or not - there is administrative control over the reverse-map. This is - identical to situations involving a single host acting on behalf of - itself. - - FQDN style can be used to get around a lack of a reverse-map for - initiators only. - -
- -
- - If there is a NAT or NAPT between the security gateways, then normal IPsec - NAT traversal problems occur. In addition to the transport problem - which may be solved by other mechanisms, there is the issue of - what phase 1 and phase 2 IDs to use. While FQDN could - be used during phase 1 for the security gateway, there is no appropriate ID for phase 2. - Due to the NAT, the end systems live in different IP address spaces. - -
- -
- - If the end system is behind a NAT (perhaps SG-B), then there is, in fact, no way for - another end system to address a packet to this end system. - Not only is opportunistic encryption - impossible, but it is also impossible for any communication to - be initiate to the end system. It may be possible for this end - system to initiate in such communication. This creates an asymmetry, but this is common for - NAPT. - -
-
- -
- - When Alice and SG-A are components of the same system, they are - considered to be a host implementation. The packet sequence scenario remains unchanged. - - - Components marked Alice are the upper layers (TCP, UDP, the - application), and SG-A is the IP layer. - - - Note that tunnel mode is still required. - - - As Alice and SG-A are acting on behalf of themselves, no TXT based delegation - record is necessary for Alice to initiate. She can rely on FQDN in a - forward map. This is particularly attractive to mobile nodes such as - notebook computers at conferences. - To respond, Alice/SG-A will still need an entry in Alice's reverse-map. - -
- -
- -If there are multiple paths between Alice and Bob (as illustrated in -the diagram with SG-D), then additional DNS records are required to establish -authorization. - - -In , Alice has two ways to -exit her network: SG-A and SG-D. Previously SG-D has been ignored. Postulate -that there are routers between Alice and her set of security gateways -(denoted by the + signs and the marking of an autonomous system number for -Alice's network). Datagrams may, therefore, travel to either SG-A or SG-D en -route to Bob. - - -As long as all network connections are in good order, it does not matter how -datagrams exit Alice's network. When they reach either security gateway, the -security gateway will find the TXT delegation record in Bob's reverse-map, -and establish an SA with SG-B. - - -SG-B has no problem establishing that either of SG-A or SG-D may speak for -Alice, because Alice has published two equally weighted TXT delegation records: -
- -
- - -Alice's routers can now do any kind of load sharing needed. Both SG-A and SG-D send datagrams addressed to Bob through -their tunnel to SG-B. - - -Alice's use of non-equal weight delegation records to show preference of one gateway over another, has relevance only when SG-B -is initiating to Alice. - - -If the precedences are the same, then SG-B has a more difficult time. It -must decide which of the two tunnels to use. SG-B has no information about -which link is less loaded, nor which security gateway has more cryptographic -resources available. SG-B, in fact, has no knowledge of whether both gateways -are even reachable. - - -The Public Internet's default-free zone may well know a good route to Alice, -but the datagrams that SG-B creates must be addressed to either SG-A or SG-D; -they can not be addressed to Alice directly. - - -SG-B may make a number of choices: - -It can ignore the problem and round robin among the tunnels. This - causes losses during times when one or the other security gateway is - unreachable. If this worries Alice, she can change the weights in her - TXT delegation records. - -It can send to the gateway from which it most recently received datagrams. - This assumes that routing and reachability are symmetrical. - -It can listen to BGP information from the Internet to decide which - system is currently up. This is clearly much more complicated, but if SG-B is already participating - in the BGP peering system to announce Bob, the results data may already - be available to it. - -It can refuse to negotiate the second tunnel. (It is unclear whether or -not this is even an option.) - -It can silently replace the outgoing portion of the first tunnel with the -second one while still retaining the incoming portions of both. SG-B can, -thus, accept datagrams from either SG-A or SG-D, but -send only to the gateway that most recently re-keyed with it. - - - - -Local policy determines which choice SG-B makes. Note that even if SG-B has perfect -knowledge about the reachability of SG-A and SG-D, Alice may not be reachable -from either of these security gateways because of internal reachability -issues. - - - -FreeS/WAN implements option 5. Implementing a different option is -being considered. The multi-homing aspects of OE are not well developed and may -be the subject of a future document. - - -
- -
-
- - If a DNS server fails to respond, local policy decides - whether or not to permit communication in the clear as embodied in - the connection classes in . - It is easy to mount a denial of service attack on the DNS server - responsible for a particular network's reverse-map. - Such an attack may cause all communication with that network to go in - the clear if the policy is permissive, or fail completely - if the policy is paranoid. Please note that this is an active attack. - - - There are still many networks - that do not have properly configured reverse-maps. Further, if the policy is not to communicate, - the above denial of service attack isolates the target network. Therefore, the decision of whether -or not to permit communication in the clear MUST be a matter of local policy. - -
- -
- - DNS records claim that opportunistic encryption should - occur, but the target gateway either does not respond on port 500, or - refuses the proposal. This may be because of a crash or reboot, a - faulty configuration, or a firewall filtering port 500. - - - The receipt of ICMP port, host or network unreachable - messages indicates a potential problem, but MUST NOT cause communication - to fail - immediately. ICMP messages are easily forged by attackers. If such a - forgery caused immediate failure, then an active attacker could easily - prevent any - encryption from ever occurring, possibly preventing all communication. - - - In these situations a clear log should be produced - and local policy should dictate if communication is then - permitted in the clear. - -
- -
- -Tunnels sometimes go down because the remote end crashes, -disconnects, or has a network link break. In general there is no -notification of this. Even in the event of a crash and successful reboot, -other SGs don't hear about it unless the rebooted SG has specific -reason to talk to them immediately. Over-quick response to temporary -network outages is undesirable. Note that a tunnel can be torn -down and then re-established without any effect visible to the user -except a pause in traffic. On the other hand, if one end reboots, -the other end can't get datagrams to it at all (except via -IKE) until the situation is noticed. So a bias toward quick -response is appropriate even at the cost of occasional -false alarms. - - - -A mechanism for recovery after reboot is a topic of current research and is not specified in this -document. - - - -A deliberate shutdown should include an attempt, using deletes, to notify all other SGs -currently connected by phase 1 SAs that communication is -about to fail. Again, a remote SG will assume this is a teardown. Attempts by the -remote SGs to negotiate new tunnels as replacements should be ignored. When possible, -SGs should attempt to preserve information about currently-connected SGs in non-volatile storage, so -that after a crash, an Initial-Contact can be sent to previous partners to -indicate loss of all previously established connections. - - -
-
- - - -
-
- - The method of obtaining information by reverse DNS lookup causes - problems for people who cannot control their reverse DNS - bindings. This is an unresolved problem in this version, and is out - of scope. - -
-
- -
- -
- - -Two example scenarios follow. In the first example GW-A -(Gateway A) and GW-B (Gateway B) have always-clear-text policies, and in the second example they have an OE -policy. The clear-text policy serves as a reference for what occurs in -TCP/IP in the absence of Opportunistic Encryption. - - -Alice wants to communicate with Bob. Perhaps she wants to retrieve a -web page from Bob's web server. In the absence of opportunistic -encryptors, the following events occur: - - -
- - Application looks up - name in DNS to get - IP address. - - <-----(3)--------------- - Resolver returns "A" RR - to application with IP - address. - - (4) - Application starts a TCP session - or UDP session and OS sends - first datagram - - ----(5)-----> - Datagram is seen at first gateway - from Alice (SG-A). - - ----------(6)------> - Datagram traverses - network. - - ------(7)-----> - Datagram arrives - at Bob, is provided - to TCP. - - <------(8)------ - A reply is sent. - - <----------(9)------ - Datagram traverses - network. - <----(10)----- - Alice receives - answer. - - (11)-----------> - A second exchange - occurs. - ----------(12)-----> - --------------> - <--------------- - <------------------- - <------------- - ]]> -
- - -
- -
- - -In the presence of properly configured opportunistic encryptors, the -event list is extended. Only changes are annotated. - - -The following symbols are used in the time-sequence diagram - - - - A single dash represents clear-text datagrams. - An equals sign represents phase 2 (IPsec) cipher-text - datagrams. - A single tilde represents clear-text phase 1 datagrams. - A hash sign represents phase 1 (IKE) cipher-text - datagrams. - - - - -
- - <-----(3)--------------- - (4)----(5)----->+ - SG-A sees datagram - to new target and - saves it as "first" - - ----(5B)-> - SG-A asks DNS - for TXT RR. - - <---(5C)-- - DNS returns TXT RR. - - ~~~~~~~~~~~~~(5D)~~~> - initial IKE main mode - packet is sent. - - <~~~~~~~~~~~~(5E1)~~~ - ~~~~~~~~~~~~~(5E2)~~> - <~~~~~~~~~~~~(5E3)~~~ - IKE phase 1 - privacy. - - #############(5E4)##> - SG-A sends ID to SG-B - <----(5F1)-- - SG-B asks DNS - for SG-A's public - KEY - -----(5F2)-> - DNS provides KEY RR. - SG-B authenticates SG-A - - <############(5E5)### - IKE phase 1 - complete - - #############(5G1)##> - IKE phase 2 - Alice<->Bob - tunnel is proposed. - - <----(5H1)-- - SG-B asks DNS for - Alice's TXT record. - -----(5H2)-> - DNS replies with TXT - record. SG-B checks - SG-A's authorization. - - <############(5G2)### - SG-B accepts proposal. - - #############(5G3)##> - SG-A confirms. - - ============(6)====> - SG-A sends "first" - packet in new IPsec - SA. - ------(7)-----> - packet is decrypted - and forward to Bob. - <------(8)------ - <==========(9)====== - return packet also - encrypted. - <-----(10)---- - - (11)-----------> - a second packet - is sent by Alice - ==========(12)=====> - existing tunnel is used - --------------> - <--------------- - <=================== - <------------- - ]]> -
- - - - - For the purposes of this section, we will describe only the changes that - occur between and - . This corresponds to time points 5, 6, 7, 9 and 10 on the list above. - - - - - At point (5), SG-A intercepts the datagram because this source/destination pair lacks a policy -(the non-existent policy state). SG-A creates a hold policy, and buffers the datagram. SG-A requests keys from the keying daemon. - - - - SG-A's IKE daemon, having looked up the source/destination pair in the connection - class list, creates a new Potential OE connection instance. SG-A starts DNS - queries. - -
- -
- - - DNS returns properly formed TXT delegation records, and SG-A's IKE daemon - causes this instance to make a transition from Potential OE connection to Pending OE - connection. - - - - Using the example above, the returned record might contain: - -
- -
- with SG-B's IP address and public key listed. - - -
- -
- Upon entering Pending OE connection, SG-A sends the initial ISAKMP - message with proposals. See . - -
- -
- - SG-B receives the message. A new connection instance is created in the - unauthenticated OE peer state. - -
- -
- - SG-A sends a Diffie-Hellman exponent. This is an internal state of the - keying daemon. - -
- -
- - SG-B responds with a Diffie-Hellman exponent. This is an internal state of the - keying protocol. - -
- -
- - SG-A uses the phase 1 SA to send its identity under encryption. - The choice of identity is discussed in . - This is an internal state of the keying protocol. - -
- -
- - SG-B asks DNS for the public key of the initiator. - DNS looks for a KEY record by IP address in the reverse-map. - That is, a KEY resource record is queried for 4.1.1.192.in-addr.arpa - (recall that SG-A's external address is 192.1.1.4). - SG-B uses the resulting public key to authenticate the initiator. See for further details. - -
- -
- -Upon successfully authenticating the peer, the connection instance makes a -transition to authenticated OE peer on SG-B. - - -The format of the TXT record returned is described in -. - -
- -
- - SG-B sends its ID along with authentication material. This is an internal - state for the keying protocol. - -
- -
-
- - Having established mutually agreeable authentications (via KEY) and - authorizations (via TXT), SG-A proposes to create an IPsec tunnel for - datagrams transiting from Alice to Bob. This tunnel is established only for - the Alice/Bob combination, not for any subnets that may be behind SG-A and SG-B. - -
- -
- - While the identity of SG-A has been established, its authority to - speak for Alice has not yet been confirmed. SG-B does a reverse - lookup on Alice's address for a TXT record. - - Upon receiving this specific proposal, SG-B's connection instance - makes a transition into the potential OE connection state. SG-B may already have an - instance, and the check is made as described above. -
- -
- - The returned key and IP address should match that of SG-A. - -
- -
- - Should additional communication occur between, for instance, Dave and Bob using - SG-A and SG-B, a new tunnel (phase 2 SA) would be established. The phase 1 SA - may be reusable. - - SG-A, having successfully keyed the tunnel, now makes a transition from - Pending OE connection to Keyed OE connection. - - The responder MUST setup the inbound IPsec SAs before sending its reply. -
- -
- - The initiator agrees with the responder's choice and sets up the tunnel. - The initiator sets up the inbound and outbound IPsec SAs. - - - The proper authorization returned with keys prompts SG-B to make a transition - to the keyed OE connection state. - - Upon receipt of this message, the responder may now setup the outbound - IPsec SAs. -
-
- -
- - SG-A sends the datagram saved at step (5) through the newly created - tunnel to SG-B, where it gets decrypted and forwarded. - Bob receives it at (7) and replies at (8). - -
- -
- - At (9), SG-B has already established an SPD entry mapping Bob->Alice via a - tunnel, so this tunnel is simply applied. The datagram is encrypted to SG-A, - decrypted by SG-A and passed to Alice at (10). - - -
-
- - - -
- -
- - Configured tunnels are those which are setup using bilateral mechanisms: exchanging -public keys (raw RSA, DSA, PKIX), pre-shared secrets, or by referencing keys that -are in known places (distinguished name from LDAP, DNS). These keys are then used to -configure a specific tunnel. - - -A pre-configured tunnel may be on all the time, or may be keyed only when needed. -The end points of the tunnel are not necessarily static: many mobile -applications (road warrior) are considered to be configured tunnels. - - -The primary characteristic is that configured tunnels are assigned specific -security properties. They may be trusted in different ways relating to exceptions to -firewall rules, exceptions to NAT processing, and to bandwidth or other quality of service restrictions. - - -Opportunistic tunnels are not inherently trusted in any strong way. They are -created without prior arrangement. As the two parties are strangers, there -MUST be no confusion of datagrams that arrive from opportunistic peers and -those that arrive from configured tunnels. A security gateway MUST take care -that an opportunistic peer can not impersonate a configured peer. - - -Ingress filtering MUST be used to make sure that only datagrams authorized by -negotiation (and the concomitant authentication and authorization) are -accepted from a tunnel. This is to prevent one peer from impersonating another. - - -An implementation suggestion is to treat opportunistic tunnel -datagrams as if they arrive on a logical interface distinct from other -configured tunnels. As the number of opportunistic tunnels that may be -created automatically on a system is potentially very high, careful attention -to scaling should be taken into account. - - -As with any IKE negotiation, opportunistic encryption cannot be secure -without authentication. Opportunistic encryption relies on DNS for its -authentication information and, therefore, cannot be fully secure without -a secure DNS. Without secure DNS, opportunistic encryption can protect against passive -eavesdropping but not against active man-in-the-middle attacks. - -
- -
- - Typical usage of per datagram access control lists is to implement various -kinds of security gateways. These are typically called "firewalls". - - - Typical usage of a virtual private network (VPN) within a firewall is to -bypass all or part of the access controls between two networks. Additional -trust (as outlined in the previous section) is given to datagrams that arrive -in the VPN. - - - Datagrams that arrive via opportunistically configured tunnels MUST not be -trusted. Any security policy that would apply to a datagram arriving in the -clear SHOULD also be applied to datagrams arriving opportunistically. - -
- -
- - There are several different forms of denial of service that an implementor - should concern themselves with. Most of these problems are shared with - security gateways that have large numbers of mobile peers (road warriors). - - - The design of ISAKMP/IKE, and its use of cookies, defend against many kinds - of denial of service. Opportunism changes the assumption that if the phase 1 (ISAKMP) - SA is authenticated, that it was worthwhile creating. Because the gateway will communicate with any machine, it is - possible to form phase 1 SAs with any machine on the Internet. - - -
-
- -
- - There are no known numbers which IANA will need to manage. - -
- -
- - Substantive portions of this document are based upon previous work by - Henry Spencer. - - - Thanks to Tero Kivinen, Sandy Harris, Wes Hardarker, Robert Moskowitz, - Jakob Schlyter, Bill Sommerfeld, John Gilmore and John Denker for their - comments and constructive criticism. - - - Sandra Hoffman and Bill Dickie did the detailed proof reading and editing. - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -