Annotation of embedaddon/strongswan/src/libcharon/sa/child_sa.h, revision 1.1
1.1 ! misho 1: /*
! 2: * Copyright (C) 2006-2019 Tobias Brunner
! 3: * Copyright (C) 2006-2008 Martin Willi
! 4: * Copyright (C) 2006 Daniel Roethlisberger
! 5: * HSR Hochschule fuer Technik Rapperswil
! 6: *
! 7: * This program is free software; you can redistribute it and/or modify it
! 8: * under the terms of the GNU General Public License as published by the
! 9: * Free Software Foundation; either version 2 of the License, or (at your
! 10: * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
! 11: *
! 12: * This program is distributed in the hope that it will be useful, but
! 13: * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
! 14: * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
! 15: * for more details.
! 16: */
! 17:
! 18: /**
! 19: * @defgroup child_sa child_sa
! 20: * @{ @ingroup sa
! 21: */
! 22:
! 23: #ifndef CHILD_SA_H_
! 24: #define CHILD_SA_H_
! 25:
! 26: typedef enum child_sa_state_t child_sa_state_t;
! 27: typedef enum child_sa_outbound_state_t child_sa_outbound_state_t;
! 28: typedef struct child_sa_t child_sa_t;
! 29: typedef struct child_sa_create_t child_sa_create_t;
! 30:
! 31: #include <library.h>
! 32: #include <crypto/prf_plus.h>
! 33: #include <encoding/payloads/proposal_substructure.h>
! 34: #include <crypto/proposal/proposal.h>
! 35: #include <config/child_cfg.h>
! 36:
! 37: /**
! 38: * States of a CHILD_SA
! 39: */
! 40: enum child_sa_state_t {
! 41:
! 42: /**
! 43: * Just created, uninstalled CHILD_SA
! 44: */
! 45: CHILD_CREATED,
! 46:
! 47: /**
! 48: * Installed SPD, but no SAD entries
! 49: */
! 50: CHILD_ROUTED,
! 51:
! 52: /**
! 53: * Installing an in-use CHILD_SA
! 54: */
! 55: CHILD_INSTALLING,
! 56:
! 57: /**
! 58: * Installed both SAs of a CHILD_SA
! 59: */
! 60: CHILD_INSTALLED,
! 61:
! 62: /**
! 63: * While updating hosts, in update_hosts()
! 64: */
! 65: CHILD_UPDATING,
! 66:
! 67: /**
! 68: * CHILD_SA which is rekeying
! 69: */
! 70: CHILD_REKEYING,
! 71:
! 72: /**
! 73: * CHILD_SA that was rekeyed, but stays installed
! 74: */
! 75: CHILD_REKEYED,
! 76:
! 77: /**
! 78: * CHILD_SA negotiation failed, but gets retried
! 79: */
! 80: CHILD_RETRYING,
! 81:
! 82: /**
! 83: * CHILD_SA in progress of delete
! 84: */
! 85: CHILD_DELETING,
! 86:
! 87: /**
! 88: * CHILD_SA has been deleted, but not yet destroyed
! 89: */
! 90: CHILD_DELETED,
! 91:
! 92: /**
! 93: * CHILD_SA object gets destroyed
! 94: */
! 95: CHILD_DESTROYING,
! 96: };
! 97:
! 98: /**
! 99: * enum strings for child_sa_state_t.
! 100: */
! 101: extern enum_name_t *child_sa_state_names;
! 102:
! 103: /**
! 104: * States of the outbound SA of a CHILD_SA
! 105: */
! 106: enum child_sa_outbound_state_t {
! 107:
! 108: /**
! 109: * Outbound SA is not installed
! 110: */
! 111: CHILD_OUTBOUND_NONE = 0,
! 112:
! 113: /**
! 114: * Data for the outbound SA has been registered during a rekeying (not set
! 115: * once the SA and policies are both installed)
! 116: */
! 117: CHILD_OUTBOUND_REGISTERED = (1<<0),
! 118:
! 119: /**
! 120: * The outbound SA has been installed
! 121: */
! 122: CHILD_OUTBOUND_SA = (1<<1),
! 123:
! 124: /**
! 125: * The outbound policies have been installed
! 126: */
! 127: CHILD_OUTBOUND_POLICIES = (1<<2),
! 128:
! 129: /**
! 130: * The outbound SA and policies are both installed
! 131: */
! 132: CHILD_OUTBOUND_INSTALLED = (CHILD_OUTBOUND_SA|CHILD_OUTBOUND_POLICIES),
! 133: };
! 134:
! 135: /**
! 136: * enum strings for child_sa_outbound_state_t.
! 137: */
! 138: extern enum_name_t *child_sa_outbound_state_names;
! 139:
! 140: /**
! 141: * Represents an IPsec SAs between two hosts.
! 142: *
! 143: * A child_sa_t contains two SAs. SAs for both
! 144: * directions are managed in one child_sa_t object. Both
! 145: * SAs and the policies have the same reqid.
! 146: *
! 147: * The procedure for child sa setup is as follows:
! 148: * - A gets SPIs for a all protocols in its proposals via child_sa_t.alloc
! 149: * - A send the proposals with the allocated SPIs to B
! 150: * - B selects a suitable proposal
! 151: * - B allocates an SPI for the selected protocol
! 152: * - B calls child_sa_t.install for both, the allocated and received SPI
! 153: * - B sends the proposal with the allocated SPI to A
! 154: * - A calls child_sa_t.install for both, the allocated and received SPI
! 155: *
! 156: * Once SAs are set up, policies can be added using add_policies.
! 157: */
! 158: struct child_sa_t {
! 159:
! 160: /**
! 161: * Get the name of the config this CHILD_SA uses.
! 162: *
! 163: * @return name
! 164: */
! 165: char* (*get_name) (child_sa_t *this);
! 166:
! 167: /**
! 168: * Get the reqid of the CHILD SA.
! 169: *
! 170: * Every CHILD_SA has a reqid. The kernel uses this ID to
! 171: * identify it.
! 172: *
! 173: * @return reqid of the CHILD SA
! 174: */
! 175: uint32_t (*get_reqid)(child_sa_t *this);
! 176:
! 177: /**
! 178: * Get the unique numerical identifier for this CHILD_SA.
! 179: *
! 180: * While the same reqid might be shared between multiple SAs, the unique_id
! 181: * is truly unique for all CHILD_SA instances.
! 182: *
! 183: * @return unique CHILD_SA identifier
! 184: */
! 185: uint32_t (*get_unique_id)(child_sa_t *this);
! 186:
! 187: /**
! 188: * Get the config used to set up this child sa.
! 189: *
! 190: * @return child_cfg
! 191: */
! 192: child_cfg_t* (*get_config) (child_sa_t *this);
! 193:
! 194: /**
! 195: * Get the state of the CHILD_SA.
! 196: *
! 197: * @return CHILD_SA state
! 198: */
! 199: child_sa_state_t (*get_state)(child_sa_t *this);
! 200:
! 201: /**
! 202: * Get the state of the outbound SA.
! 203: *
! 204: * @return outbound SA state
! 205: */
! 206: child_sa_outbound_state_t (*get_outbound_state)(child_sa_t *this);
! 207:
! 208: /**
! 209: * Set the state of the CHILD_SA.
! 210: *
! 211: * @param state state to set on CHILD_SA
! 212: */
! 213: void (*set_state) (child_sa_t *this, child_sa_state_t state);
! 214:
! 215: /**
! 216: * Get the SPI of this CHILD_SA.
! 217: *
! 218: * Set the boolean parameter inbound to TRUE to
! 219: * get the SPI for which we receive packets, use
! 220: * FALSE to get those we use for sending packets.
! 221: *
! 222: * @param inbound TRUE to get inbound SPI, FALSE for outbound.
! 223: * @return SPI of the CHILD SA
! 224: */
! 225: uint32_t (*get_spi) (child_sa_t *this, bool inbound);
! 226:
! 227: /**
! 228: * Get the CPI of this CHILD_SA.
! 229: *
! 230: * Set the boolean parameter inbound to TRUE to
! 231: * get the CPI for which we receive packets, use
! 232: * FALSE to get those we use for sending packets.
! 233: *
! 234: * @param inbound TRUE to get inbound CPI, FALSE for outbound.
! 235: * @return CPI of the CHILD SA
! 236: */
! 237: uint16_t (*get_cpi) (child_sa_t *this, bool inbound);
! 238:
! 239: /**
! 240: * Get the protocol which this CHILD_SA uses to protect traffic.
! 241: *
! 242: * @return AH | ESP
! 243: */
! 244: protocol_id_t (*get_protocol) (child_sa_t *this);
! 245:
! 246: /**
! 247: * Set the negotiated protocol to use for this CHILD_SA.
! 248: *
! 249: * @param protocol AH | ESP
! 250: */
! 251: void (*set_protocol)(child_sa_t *this, protocol_id_t protocol);
! 252:
! 253: /**
! 254: * Get the IPsec mode of this CHILD_SA.
! 255: *
! 256: * @return TUNNEL | TRANSPORT | BEET
! 257: */
! 258: ipsec_mode_t (*get_mode)(child_sa_t *this);
! 259:
! 260: /**
! 261: * Set the negotiated IPsec mode to use.
! 262: *
! 263: * @param mode TUNNEL | TRANSPORT | BEET
! 264: */
! 265: void (*set_mode)(child_sa_t *this, ipsec_mode_t mode);
! 266:
! 267: /**
! 268: * Get the used IPComp algorithm.
! 269: *
! 270: * @return IPComp compression algorithm.
! 271: */
! 272: ipcomp_transform_t (*get_ipcomp)(child_sa_t *this);
! 273:
! 274: /**
! 275: * Set the IPComp algorithm to use.
! 276: *
! 277: * @param ipcomp the IPComp transform to use
! 278: */
! 279: void (*set_ipcomp)(child_sa_t *this, ipcomp_transform_t ipcomp);
! 280:
! 281: /**
! 282: * Get the action to enforce if the remote peer closes the CHILD_SA.
! 283: *
! 284: * @return close action
! 285: */
! 286: action_t (*get_close_action)(child_sa_t *this);
! 287:
! 288: /**
! 289: * Override the close action specified by the CHILD_SA config.
! 290: *
! 291: * @param close action to enforce
! 292: */
! 293: void (*set_close_action)(child_sa_t *this, action_t action);
! 294:
! 295: /**
! 296: * Get the action to enforce if the peer is considered dead.
! 297: *
! 298: * @return dpd action
! 299: */
! 300: action_t (*get_dpd_action)(child_sa_t *this);
! 301:
! 302: /**
! 303: * Override the DPD action specified by the CHILD_SA config.
! 304: *
! 305: * @param dpd action to enforce
! 306: */
! 307: void (*set_dpd_action)(child_sa_t *this, action_t action);
! 308:
! 309: /**
! 310: * Get the selected proposal.
! 311: *
! 312: * @return selected proposal
! 313: */
! 314: proposal_t* (*get_proposal)(child_sa_t *this);
! 315:
! 316: /**
! 317: * Set the negotiated proposal.
! 318: *
! 319: * @param proposal selected proposal
! 320: */
! 321: void (*set_proposal)(child_sa_t *this, proposal_t *proposal);
! 322:
! 323: /**
! 324: * Check if this CHILD_SA uses UDP encapsulation.
! 325: *
! 326: * @return TRUE if SA encapsulates ESP packets
! 327: */
! 328: bool (*has_encap)(child_sa_t *this);
! 329:
! 330: /**
! 331: * Get the absolute time when the CHILD_SA expires or gets rekeyed.
! 332: *
! 333: * @param hard TRUE for hard lifetime, FALSE for soft (rekey) lifetime
! 334: * @return absolute time
! 335: */
! 336: time_t (*get_lifetime)(child_sa_t *this, bool hard);
! 337:
! 338: /**
! 339: * Get the absolute time when this SA has been installed.
! 340: *
! 341: * @return monotonic absolute install time
! 342: */
! 343: time_t (*get_installtime)(child_sa_t *this);
! 344:
! 345: /**
! 346: * Get last use time and the number of bytes processed.
! 347: *
! 348: * @param inbound TRUE for inbound traffic, FALSE for outbound
! 349: * @param[out] time time of last use in seconds (NULL to ignore)
! 350: * @param[out] bytes number of processed bytes (NULL to ignore)
! 351: * @param[out] packets number of processed packets (NULL to ignore)
! 352: */
! 353: void (*get_usestats)(child_sa_t *this, bool inbound, time_t *time,
! 354: uint64_t *bytes, uint64_t *packets);
! 355:
! 356: /**
! 357: * Get the mark used with this CHILD_SA.
! 358: *
! 359: * @param inbound TRUE to get inbound mark, FALSE for outbound
! 360: * @return mark used with this CHILD_SA
! 361: */
! 362: mark_t (*get_mark)(child_sa_t *this, bool inbound);
! 363:
! 364: /**
! 365: * Get the interface ID used with this CHILD_SA.
! 366: *
! 367: * @param inbound TRUE to get inbound ID, FALSE for outbound
! 368: * @return interface ID used with this CHILD_SA
! 369: */
! 370: uint32_t (*get_if_id)(child_sa_t *this, bool inbound);
! 371:
! 372: /**
! 373: * Create an enumerator over traffic selectors of one side.
! 374: *
! 375: * @param local TRUE for own traffic selectors, FALSE for remote.
! 376: * @return enumerator over traffic_selector_t*
! 377: */
! 378: enumerator_t* (*create_ts_enumerator)(child_sa_t *this, bool local);
! 379:
! 380: /**
! 381: * Create an enumerator over installed policies.
! 382: *
! 383: * The enumerated traffic selectors is a full mesh of compatible local
! 384: * and remote traffic selectors.
! 385: *
! 386: * @return enumerator over a pair of traffic_selector_t*
! 387: */
! 388: enumerator_t* (*create_policy_enumerator)(child_sa_t *this);
! 389:
! 390: /**
! 391: * Allocate an SPI to include in a proposal.
! 392: *
! 393: * @param protocol protocol to allocate SPI for (ESP|AH)
! 394: * @param spi SPI output pointer
! 395: * @return SPI, 0 on failure
! 396: */
! 397: uint32_t (*alloc_spi)(child_sa_t *this, protocol_id_t protocol);
! 398:
! 399: /**
! 400: * Allocate a CPI to use for IPComp.
! 401: *
! 402: * @return CPI, 0 on failure
! 403: */
! 404: uint16_t (*alloc_cpi)(child_sa_t *this);
! 405:
! 406: /**
! 407: * Install an IPsec SA for one direction.
! 408: *
! 409: * set_policies() should be called before calling this.
! 410: *
! 411: * @param encr encryption key, if any
! 412: * @param integ integrity key
! 413: * @param spi SPI to use, allocated for inbound
! 414: * @param cpi CPI to use, allocated for outbound
! 415: * @param initiator TRUE if initiator of exchange resulting in this SA
! 416: * @param inbound TRUE to install an inbound SA, FALSE for outbound
! 417: * @param tfcv3 TRUE if peer supports ESPv3 TFC
! 418: * @return SUCCESS or FAILED
! 419: */
! 420: status_t (*install)(child_sa_t *this, chunk_t encr, chunk_t integ,
! 421: uint32_t spi, uint16_t cpi,
! 422: bool initiator, bool inbound, bool tfcv3);
! 423:
! 424: /**
! 425: * Register data for the installation of an outbound SA as responder during
! 426: * a rekeying.
! 427: *
! 428: * If the kernel is able to handle SPIs on policies the SA is installed
! 429: * immediately, if not it won't be installed until install_outbound() is
! 430: * called.
! 431: *
! 432: * @param encr encryption key, if any (cloned)
! 433: * @param integ integrity key (cloned)
! 434: * @param spi SPI to use, allocated for inbound
! 435: * @param cpi CPI to use, allocated for outbound
! 436: * @param tfcv3 TRUE if peer supports ESPv3 TFC
! 437: * @return SUCCESS or FAILED
! 438: */
! 439: status_t (*register_outbound)(child_sa_t *this, chunk_t encr, chunk_t integ,
! 440: uint32_t spi, uint16_t cpi, bool tfcv3);
! 441:
! 442: /**
! 443: * Install the outbound policies and, if not already done, the outbound SA
! 444: * as responder during a rekeying.
! 445: *
! 446: * @return SUCCESS or FAILED
! 447: */
! 448: status_t (*install_outbound)(child_sa_t *this);
! 449:
! 450: /**
! 451: * Remove the outbound SA and the outbound policies after a rekeying.
! 452: */
! 453: void (*remove_outbound)(child_sa_t *this);
! 454:
! 455: /**
! 456: * Configure the policies using some traffic selectors.
! 457: *
! 458: * Supplied lists of traffic_selector_t's specify the policies
! 459: * to use for this child sa.
! 460: *
! 461: * Install the policies by calling install_policies().
! 462: *
! 463: * This should be called before calling install() so the traffic selectors
! 464: * may be passed to the kernel interface when installing the SAs.
! 465: *
! 466: * @param my_ts traffic selectors for local site (cloned)
! 467: * @param other_ts traffic selectors for remote site (cloned)
! 468: */
! 469: void (*set_policies)(child_sa_t *this, linked_list_t *my_ts_list,
! 470: linked_list_t *other_ts_list);
! 471:
! 472: /**
! 473: * Install the configured policies.
! 474: *
! 475: * If register_outbound() was called previously this only installs the
! 476: * inbound and forward policies, the outbound policies are installed when
! 477: * install_outbound() is called.
! 478: *
! 479: * @return SUCCESS or FAILED
! 480: */
! 481: status_t (*install_policies)(child_sa_t *this);
! 482:
! 483: /**
! 484: * Set the outbound SPI of the CHILD_SA that replaced this CHILD_SA during
! 485: * a rekeying.
! 486: *
! 487: * @param spi outbound SPI of the CHILD_SA that replaced this CHILD_SA
! 488: */
! 489: void (*set_rekey_spi)(child_sa_t *this, uint32_t spi);
! 490:
! 491: /**
! 492: * Get the outbound SPI of the CHILD_SA that replaced this CHILD_SA during
! 493: * a rekeying.
! 494: *
! 495: * @return outbound SPI of the CHILD_SA that replaced this CHILD_SA
! 496: */
! 497: uint32_t (*get_rekey_spi)(child_sa_t *this);
! 498:
! 499: /**
! 500: * Update hosts and ecapsulation mode in the kernel SAs and policies.
! 501: *
! 502: * @param me the new local host
! 503: * @param other the new remote host
! 504: * @param vips list of local virtual IPs
! 505: * @param encap TRUE to use UDP encapsulation for NAT traversal
! 506: * @return SUCCESS or FAILED
! 507: */
! 508: status_t (*update)(child_sa_t *this, host_t *me, host_t *other,
! 509: linked_list_t *vips, bool encap);
! 510: /**
! 511: * Destroys a child_sa.
! 512: */
! 513: void (*destroy) (child_sa_t *this);
! 514: };
! 515:
! 516: /**
! 517: * Data passed to the constructor of a child_sa_t object.
! 518: */
! 519: struct child_sa_create_t {
! 520: /** Optional reqid of old CHILD_SA when rekeying */
! 521: uint32_t reqid;
! 522: /** Optional inbound mark when rekeying */
! 523: uint32_t mark_in;
! 524: /** Optional outbound mark when rekeying */
! 525: uint32_t mark_out;
! 526: /** Optional inbound interface ID when rekeying */
! 527: uint32_t if_id_in;
! 528: /** Optional outbound interface ID when rekeying */
! 529: uint32_t if_id_out;
! 530: /** Optional default inbound interface ID, if neither if_id_in, nor config
! 531: * sets one */
! 532: uint32_t if_id_in_def;
! 533: /** Optional default outbound interface ID, if neither if_id_out, nor config
! 534: * sets one */
! 535: uint32_t if_id_out_def;
! 536: /** TRUE to enable UDP encapsulation (NAT traversal) */
! 537: bool encap;
! 538: };
! 539:
! 540: /**
! 541: * Constructor to create a child SA negotiated with IKE.
! 542: *
! 543: * @param me own address
! 544: * @param other remote address
! 545: * @param config config to use for this CHILD_SA
! 546: * @param data data for this CHILD_SA
! 547: * @return child_sa_t object
! 548: */
! 549: child_sa_t *child_sa_create(host_t *me, host_t *other, child_cfg_t *config,
! 550: child_sa_create_t *data);
! 551:
! 552: #endif /** CHILD_SA_H_ @}*/
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>